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Abstract 


Many  of  the  problems  of  large  software  systems  have 
been  attributed  to  the  design  phase  of  software  development, 
problems  such  as  high  maintenance  costs,  the  predominance 
of  software  error  types  traceable  to  design  (rather  than  to 
coding) , and  the  high  cost  of  diagnosing  and  correcting 
design  errors.  'The  most  promising  approach  to  these 
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problems  is  the  formal  specification  of  module  interfaces, 

A 

during  the  design  phase,  based  on  the  information-hiding 
principle. 

The  advantages  of  formal  specifications  are  as  follows: 
(1)  Their  precision,  lack  of  ambiguity,  and  attention  to 
detail  should  cut  down  on  design  errors.  (2)  They 
provide  informal  verification  of  a hierarchically  designed 
system  while  it  is  being  designed.  (3)  Special  design 
validation  teams  could  rigorously  verify  a design  before 
it  is  implemented,  perhaps  with  the  aid  of  automated  tools 
for  some  of  the  verification.  (4)  Formal  specification 
enables  rigorous  specification  of  the  requirements  that  an 
embedded  computer  system  must  conform  to.  (5)  They 
combine  with  the  information-hiding  principle  to  enable 
design  of  systems  that  are  much  easier  to  modify  and 
maintain. 

* Yet,  the  formal  specification  of  modules  itself  has  a 
serious  drawback:  the  upfront  effort  in  creating  them  is 
considerable.  Consequently , N this  research  has  investigated 
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the  feasibility  of  a library  of  formal  specifications  so 
that  designers  could  build  on  the  work  of  others  and  thereby 
significantly  cut  the  upfront  effort  involved.  \ We  have 
identified  five  issues  as  paramount  to  the  feasibility  of 
such  a library,  and  have  concentrated  on  adapting 
methodological  techniques  already  familiar  in  software 
engineering. 
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1.  Conclusions  and  Recommendations 


This  final  report  is  organized  as  follows:  this 
section  briefly  summarizes  the  conclusions  and  recommen- 
dations of  the  research  after  a very  short  exposition  of 
the  purpose  of  the  project.  Section  2 introduces  the 
research  by  explaining  its  motivation  and  purpose.  Sec- 
tion 3 introduces  the  major  issues  that  we  considered. 
In  section  4,  we  itemize  exactly  what  we  did  and  the 
analysis  techniques  used.  Detailed  results  are  justi- 
fied in  section  5.  The  relation  of  this  work  to  that  of 
others  appears  in  section  6.  Several  appendices  are 
included.  One  describes  the  specification  language  used 
in  the  examples;  the  remaining  four  are  a small  sampling 
of  module  specifications  written  durinq  the  course  of 
the  project.  ' 

1.1  Brief  introduction 

Large  software  systems  can  be  defined  as  systems 
requiring  at  least  25  programmers  to  develop  and  requir- 
ing at  least  30,000  lines  of  source  code.  Case  studies 
(Boehm,  et.al.  (1975)  and  Hamilton  and  Zeldin  (1975))  of 
such  systems  have  shown  that  software  errors  traceable 
to  the  design  phase  of  system  development  can  account 
for  as  much  as  two-thirds  to  three-quarters  of  all  error 
types,  even  on  generally  good  software  systems,  compared 
with  as  little  as  one-quarter  to  one-third  of  all  error 
types  traceable  to  the  programming  or  coding  effort. 
The  types  of  errors  traceable  to  the  design  phase  are 


predominantly  errors  in  the  interface  of  subsystems  or 
modul es. 

Desiqn  errors  and  desiqn  validation  are  particular- 
ly crucial  in  embedded  computer  systems.  An  embedded 
computer  system  is  a system  developed  specifically  to 
function  as  a component  of  a larqer  system. 

A desiqn  technique  to  address  these  problems  was 
developed  by  Parnas  (1972).  It  concentrates  on  defininq 
the  interface  of  a module  in  enouqh  detail  that  all  oth- 
er systems  may  use  it,  but  completely  independent  of  the 
way  the  module  may  be  Implemented.  Since  programming 
languages  focus  attention  on  how  to  implement  a module, 
several  new  languages  for  formally  specifying  the  inter- 
face of  modules  have  been  developed  in  the  last  few 
years.  , 

The  technique  of  formal  module  specifications  seems 
to  offer  much  toward  solving  many  problems  including: 
the  high  cost  of  software  maintenance,  the  predominance 
of  design  errors,  the  difficulty  and  cost  of  diaqnosing 
and  correcting  design  errors,  and  the  special  design  and 
maintenance  problems  of  embedded  computer  systems.  Yet, 
the  creatinq  of  formal  specifications  is  very  difficult, 
requiring  much  upfront  effort,  and  therefore  the  solu- 
tion itself  is  rather  costly. 

The  natural  solution  is  to  develop  a library  of 
formal  specifications  of  modules.  By  reusing  module 
specifications,  rather  than  recreating  them,  the  cost  of 
the  upfront  effort  would  be  dramatically  cut  and  the 
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problems  listed  in  the  preceding  paragraph  would  be 
so lved . 

That  i s the  motivation  of  this  research  in 
ex  am i n i ng  the  feasibility  of  such  a 1 ibrary . Several 
issues  are  involved  in  such  a library  being  feasible. 
To  answer  each  question  about  the  feasibility  of  a li- 
brary of  formal  module  specifications,  we  have  given 
special  attention  to  techniques  that  are  al ready 
available  in  software  practice  and  could  be  adapted  to 
these  particular  questions  regard inq  the  feaslbil ity  of 
a 1 ibrary , (rather  than  spending  effort  on  developing 
yet  another  language  or  another  methodology) . Since 
formal  spec i f leaf  ions  are  so  ha  rd  to  create  and  demand  a 
way  of  thinking  about  desig n which  is  rather  new  to  most 
* Individuals,  our  focus i ng  on  famil iar  so  f twa  re 

techniques  that  coul d be  adapted  to  the  probl ems  of  such 
a 1 ibrary  has  the  additional  benef i t of  maki ng  the 
library  far  more  practical  and  usable . 


1.2.  Summary  of  conclusions 

Three  techniques  have  proven  very  useful  for 

* 

detecting  flaws,  omissions,  and  errors  in  the  formal 

I 

specifications  of  module  interfaces.  One  is  an  automat- 
ic tool  (Roubine  and  Robinson,  19^6)  which  checks  for  l 

syntactic  correctness  and  some  simple  semantic  problems, 

■ 

1 

such  as  referenced  but  undefined  functions  or  variables. 

A second  is  a walkthrough  to  check  the  correctness  and 
completeness  of  the  interface  and  to  criticize  the 

I I 
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readability  of  the  speci f ication.  ( Fo r a library  of 
such  spec i f icat ions , the  guidel ines  we  have  suggested 
for  documentat ion  would  enable  each  user  of  the  library, 
1 n essence , to  per  fo  rm  a walkthrough  of  the 
speci f ication , i n fo  rmal 1 y check i ng  its  correctness . 
Thus , with  each  use  of  a nodul e from  the  1 ibrary , our 
conf idence  in  the  correctness  of  the  speci f ication  can 
justl f iably  increase. ) The  third  technique  is  to  write  a 
very  rapid  implementation  oZ  the  specified  module  in  a 
very  high-level  language.  Each  technique  uncovers  flaws 
or  omissions  in  the  specification. 

Rigorous  design  validation  before  coding  even  be- 
gins would  be  possible  using  formal  specifications, 
since  an  independent  verification  and  validation  team 
could  be  called  in  to  verify  the  design.  For  instance, 
the  designs  of  two  operating  systems,  (Neumann,  et.al.r 
1977  and  Ford  Aerospace,  1978)  have  been  proven  to  main- 
tain certain  security  properties  before  implementation 
began . 

Automatic  retrieval  of  module  speci f ications  from  a 
library  is  analogous  to  the  bibliographic  retrieval 
problem.  Since  that  is  such  a difficult  problem  involv- 
ing so  many  research  projects,  we  concluded  not  to  ad- 
dress that  aspect  further,  but  merely  suggest  the  use  of 
techniques  such  as  keyword  analysis. 

For  a given  application,  it  is  crucial  that  only  a 
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considered,  too  much  of  the  designers'  time  will  be  tak- 
en studying  the  many  alternatives.  Since  the  formal 
specifications  are  difficult  to  understand,  it  is  un- 
realistic to  expect  that  a designer  can  carefully  study 
more  than  a handful. 

In  the  examples  we  have  written  during  the 
research,  we  have  found  that  two  to  four  prototypes  seem 
to  cover  most  needs  for  a particular  type  of  data  struc- 
ture and  three  prototype  text  editors  seem  to  cover  most 
varieties  of  text  editors.  This  was  accomplished  by 
following  three  principles  for  writing  and  selecting 
prototypes  for  the  library. 

1)  Details  that  are  somewhat  arbi- 
trary and  which  the  designer  may 
wish  to  modify  should  be  localized 
into  subdefinitions  so  that  the 
modifier  need  modify  the  specifica- 
tion in  only  one  place  for  each 
detail . 

2)  Aspects  of  the  module  that  are 
not  fundamental  need  not  be  speci- 
fied in  the  library.  A whole  host 
of  valid  command  languages  may  be 
added  on  to  the  logical  abilities  of 
any  given  text  editor;  therefore, 
our  prototype  specifications  did  not 
include  a command  language. 


3)  The  prototype  should  include  as 
many  logically  different  operations 
as  possible,  since  the  designer  can 
easily  delete  ones  unneeded  in  a 
particular  environment. 

Although  the  results  using  the  three  principles  are 
very  promising,  we  simply  have  insufficient  evidence  to 
judge  whether  application  areas  other  than  data  struc- 
tures and  text  editors  will  also  be  covered  by  only  a 
handful  of  prototypes.  Further  research  and  experience 
is  definitely  needed  to  answer  this  question. 

A third  issue  is  what  to  store  in  the  library. 
Clearly,  the  specifications  of  the  module  interfaces 
must  he  stored,  for  this  is  prerequisite  to  the  modern 
design  methodology  proposed  by  Parnas  and  many  others  to 
solve  the  problems  of  large  software  systems  and  embed- 
ded computer  systems.  For  any  specification,  many 
hierarchical  program  designs  and  many  programs  imple- 
menting it  are  possible.  Each  will  have  differing  space 
and  time  requirements,  and  therefore  are  necessary  al- 
ternatives for  differing  environments.  This  could  in- 
volve several  programs  for  each  prototype  module  inter- 
face. Furthermore,  the  need  of  a designer  to  tailor  the 
interface  of  the  module  slightly  for  his/her  particular 
needs,  as  one  would  expect  to  happen  normally,  requires 
modifying  any  selected  program  implementing  the  module. 
Consequently,  we  have  no  definite  answer  as  to  whether 
storing  the  alternative  implementations  as  well  is 
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feasible. 

We  have  identified  six  items  that  must  he  stored 
with  the  module  specification  as  documentation.  These 
are  short  descriptive  items  desiqned  to  enable  a 
designer  to  quickly  identify  a handful  of  interface 
spec i f icat ions  that  are  closest  to  his/her  needs. 

Since  formal  module  specifications  are  so  hard  to 
understand,  a fourth  issue  is  how  to  make  them  more 
understandable.  We  have  identified  three  reasons  for 
the  difficulty  in  understanding  formal  specifications. 

Programming  languages  focus  on  implementation  de- 
tail; the  module  interfaces  must  be  specified  indepen- 
dent of  implementation  detail.  Consequently,  the  seman- 
tics of  these  languages  is  f undamental ly  different  than 
the  languages  we  are  familiar  with  for  programming. 
Therefore,  rather  than  trying  to  devise  a new  language*, 
we  have  shown  how  to  adapt  many  of  the  principles  of 
writing  well-structured,  easily  understandable  programs 
to  the  task  of  writing  understandable  module  specifica- 
tions. 

The  last  issue  is  how  to  define  the  interfaces  to 
be  stored  in  the  library  so  that  they  may  be  easily 
modified  for  or  tailored  to  the  demands  of  a specific 
environment.  Two  principles  were  discovered  for  this. 
One  is  to  localize  any  detail  that  is  somewhat  arbitrary 
in  a definition;  then,  to  modify  the  detail,  only  one 
change  need  be  made.  Second,  the  author  of  the  specifi- 
cation should  make  a list  of  the  details  that  he/she 
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suspects  mlqht  need  modi  f i cat  ion , so  th.it  the  author’s 
anticipation  of  possible  chanqes  saves  the  deslqner'a 
effort. 


1.1  Recommendat ions 

For  each  module  specification  written,  we  quickly 
implemented  a correspond  inq  proqram  in  a very  hiqh  level 
lanquaqe  as  a means  of  testinq  the  completeness  of  the 
interface  specified.  The  rapidity  with  which  we  could 
create  this  qulck-and-d i r ty  implementation  suqqests  that 
very  hiqh  level  lanquaqes  mlqht  be  the  means  of  creatlnq 
software  breadboards.  Thouqh  the  breadboard  would  be 
wasteful  of  memory  and  time,  it  could  be  created  quickly 
to  demonstrate  the  functional  characteristics  of  the 
system.  Tf  a scale  factor  for  the  speedup  and  the  econ- 
omy in  memory  usaqe  can  be  estimated  for  qolnq  from  the 
breadboard  to  a production  system,  the  breadboard  would 
also  provide  ballpark  estimates  for  the  performance  of 
the  module. 

In  this  way,  the  breadboard  would  provide  end  users 
with  actual  use  of  the  system  under  desiqn  as  a means  of 
desiqn  validation.  Furthermore,  we  found  that  a slqni- 
ficant  portion  of  the  specification  lanquaqe  features 
had  a standard  translation  into  the  very  hiqh  level 
lanquaqe.  Consequently,  a software  tool  could  be 
desiqned  to  perform  much  of  the  translation  ft  m specif- 
ication lanquaqe  to  very  hiqh  level  lanquaqe  automati- 
cally. 
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Therefore,  we  recommend  empirical  research  in  the 
use  of  an  existlnq  hlqh  level  lanquaqe,  such  as 
INTERLISP  (Teitelman,  1975),  for  the  purpose  of  rapidly 
buildinq  breadboard  systems  correspond inq  to  a deslqn. 
Research  in  buildinq  and  experimental  use  of  a semi- 
automatic tool  to  translate  a slqnificant  portion  of  the 
specifications  into  a very  hlqh  level  lanquaqe  also 
seems  to  be  a hiqh-payoff  area  for  i nvest lq at  ion . (The 
software  tool  could  not  be  fully  automatic  since  the 
specification  lanquaqe  specifically  leaves  out.  implemen- 
tation detail.  So,  some  codinq  by  a human  is  always 
necessary. ) 

Another  area  for  further  work  is  to  specify  many 
more  modules  from  a diverse  class  of  a ppl icat ions . Our 
results  were  promlslnq,  since  a handful  of  prototypes 
could  cover  most  needs  in  the  areas  of  data  structure* 
and  text  editors.  However,  our  experience  is  simply  too 
limited  to  project  whether  this  key  inqredient  to  the 
success  of  such  a library  will  carry  over  to  other  ap- 
pl  ications. 

In  the  same  way,  we  did  not  have  time  to  experiment 
with  storing  several  alternate  implementations  for  each 
module  specification.  For  this  to  be  feasible,  the 
number  of  alternate  Implementations  per  module  should  be 
small.  Also  any  requirements  to  modify  or  tailor  a pro- 
totype module  interface  to  a particular  environment  must 
be  easily  impl ementabl e changes  in  the  alternative  pro- 
grams stored  with  an  interface  specification.  This  is 
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certainly  worthy  of  further  research. 

Our  final  recommendation  is  that  a library  such  as 
we  have  proposed  should  not  be  bequn  for  actual  use 
until  specification  languages  leave  the  experimental 
stage.  These  languages,  beinq  very  younq,  will  continue 
to  be  enhanced,  particularly  in  the  area  of  specifying 
the  semantics  of  parallel  computing.  Liskov  (1977)  pro- 
vides a survey  of  the  state  of  the  art  in  specification 
languages. 
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2.  Motivation  of  the  Research 

The  attractiveness  of  having  a library  of  the  pro- 
ducts of  previous  software  development  is  the  benefit  of 
buildinq  on  the  work  of  others.  There  are  several  rea- 
sons in  particular  for  wanting  a library  of  formal 
spec i f icat ions  of  modules,  the  key  product  of  the  design 
phase  of  the  software  development  process.  We  present 
these  reasons  in  the  following  subsections. 

2.1  The  cost  of  software  and  its  maintenance 

The  high  cost  of  software  is  well-known  and  need 
not  be  belabored;  however,  the  immensity  of  the  problem 
can  be  quickly  indicated  by  such  facts  as  the  following. 
It  is  estimated  in  Boehm  (1927)  that  the  annual  cost  of 
software  in  the  United  States  is  $20  billion  dollars,  or 
almost  2%  of  the  entire  gross  national  product.  In  a 
study  for  the  Air  Force,  Boehm  (1973)  reported  that  the 
estimated  software  expenditures  of  the  Air  Force  for 
1972  were  three  times  the  hardware  expenditures.  Even 
more  startling  is  the  projection  from  the  same  study 
that  by  1985  the  annual  software  expenditures  of  the  Air 
Force  would  be  nine  times  the  hardware  expenditures. 

At  the  same  time,  the  maintenance  costs  of  software 
are  of  deep  concern.  Larqe  software  systems  are  notori- 
ously difficult  to  modify  in  response  to  changinq  needs 
or  the  discovery  of  bugs  not  found  until  delivery  of  the 
product.  For  instance,  OS/360,  a major  operating  system 
for  the  IBM  360  series  of  machines,  is  one  of  the 
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largest  software  systems  ever  developed.  It  is  estimat- 
ed, (Boehm,  1973),  that  with  each  new  release  of  the 
system,  1000  new  software  errors  were  introduced. 

Insight  into  the  causes  of  such  massive  software 
modification  problems  is  given  in  the  case  studies  cited 
in  the  next  section. 

2.2  Design  errors  and  the  importance  of  design  valida- 
tion 

A major  cause  of  the  maintenance  problems  of 
software  is  the  design  of  large  software  systems,  as 
evidenced  in  the  following  case  study  by  TRW.  Boehm 
(1975)  reports  that  the  software  studied  is  an  example 
of  a generally  good  system,  delivered  on  time  and  within 
budget  by  TRW.  The  system  consisted  of  100,000  source 
code  statements  and  underwent  five  modifications  during 
its  life  cycle,  ranging  in  size  from  just  under  1000  up 
to  10,000  source  code  statements  chanqed. 

The  errors  found  in  making  the  five  modifications 
were  categorized  into  224  types.  In  a summary  analysis, 
the  error  types  were  classified  as  to  their  oriqin, 
either  traceable  to  the  design  phase  (requiring  a modif- 
ication of  the  detailed  desiqn  description)  or  attribut- 
able to  the  coding  phase  of  software  development.  Error 
types  traceable  to  the  design  phase  tended  to  involve 
interface  problems  between  the  modules  of  the  system. 
"Not  only  did  the  number  of  types  of  design  errors 
outweigh  the  coding  error  types,  64  percent  to  36 
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percent,  but  also  the  design  errors  took  the  longest  by 
far  to  detect,"  (Boehm,  et.al.,  1975,  pp.  125-125).  In 
fact,  54  percent  of  the  error  types  were  not  found  till 
integration  test  or  later;  of  these,  5 out  of  6 were 
design  errors.  Thus,  the  overwhelming  majority  (75%)  of 
the  coding  error  types  were  found  before  integration 
test,  but  the  overwhelming  majority  (70%)  of  design 
error  types  were  undetected  until  integration  test  or 
later.  In  a related  study,  it  was  found  that  the  aver- 
age time  to  diagnose  and  correct  design-type  errors  was 
about  twice  that  of  coding  errors. 

Similar  results  have  been  reported  by  Hamilton  and 
Zeldin  (1976);  73  percent  of  all  errors  found  during 
integration  tests  of  the  APOLLO  project  were  interface 
probl  ems . 

Clearly  then,  the  design  phase  of  software 
development  is  most  cr  i tical  in  building  1 arge  so f tware 
systems  that  are  both  maintainable  and  reliable.  Design 
val idation  is  therefo  re  crucial  befo  re  coding  beg  ins. 

For  a number  of  reasons  given  in  the  next  section, 
the  formal  specification  of  modules  has  been  suggested 
by  many  computer  scientists  as  the  solution  to  these 
problems. 


2.3  The  attractiveness  of  formal  module  specifications 

By  a "module,"  we  mean  a tightly  related  group  of 
algorithms  and  data  that  provide  some  computational 
facility.  Because  of  the  aforementioned  problems  of 


-14- 


maintaininq  software,  the  information-hid  inq  principle 
was  sugqested  by  Parnas  (1972)  and  has  been  widely  ac- 
cepted since  then.  Accordinq  to  this  principle,  one 
should  modularize  a system  by  identifying  those  desiqn 
decisions  which  might  be  reversed  due  to  changing  condi- 
tions during  the  life-cycle  of  the  system.  For  each 
such  desiqn  decision,  a module  is  defined  such  that  the 
result  of  deciding  that  desiqn  issue  is  hidden  in  the 
module  and  invisible  to  processes  or  people  using  the 
module.  The  information-hiding  principle  requires  that 
there  is  a technique  for  precisely  specifying  the  inter- 
face of  a module  and  the  visible  behavior  of  the  module 
in  all  circumstances. 

In  this  way,  designers  can  completely  specify  the 
modules  of  a system  such  that  a programmer  team  can  be 
assigned  to  each  module  and  such  that  each  team  can  worW 
independently  without  knowing  any  more  about  the  other 
modules  than  the  specifications  of  the  interfaces. 
Since  each  module  depends  on  only  the  interfaces  of  the 
other  modules,  any  of  the  design  decisions  hidden  by  the 
modularization  based  on  the  information-hiding  principle 
can  be  reversed  easily,  for  only  one  module  must  be 
modified.  Parnas  (1976)  demonstrates  how  this  technique 
enables  the  specification  of  a family  of  closely  related 
software  systems  such  that  movinq  to  another  family  of 
the  system  is  much  simpler  than  would  be  otherwise  pos- 
sible. Modifications  of  a system  due  to  changing  needs 
and  environment  during  the  software's  life  cycle  is  like 
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movinq  from  one  member  of  the  family  of  systems  to 
another . 

Given  this,  there  are  several  reasons  why  formal 
module  specifications  appear  so  promising  for  software 
probl  ems . 


1)  Several  formal  languages  have 
been  developed  for  specifying  the 
interface  of  a module  according  to 
the  information-hiding  principle. 
They  define  as  much  as  is  needed  to 
know  exactly  how  to  use  the  module 
without  committing  the  module  to  any 
particular  algorithms  or  data  struc- 
tures fof-  implementing  it. 

2)  Formal  specifications  state  the 
interface  of  a module  precisely, 
unambiguously,  and  completely. 
Design  errors  resulting  from  incom- 
plete, vague,  or  ambiguous  module 
descriptions  should  be  vastly  cut 
down.  The  case  study  data  cited  in 
2.2  testifies  to  how  large  a percen- 
tage of  errors  are  related  to  inter- 
face definition  and  how  difficult 
and  expensive  it  is  to  correct  such 
errors  compared  to  coding  errors. 

3)  As  Parnas  (1977a)  points  out, 
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formal  specification  of  modules 
seems  to  be  a necessary  part  of  a 
topdown  development  or  stepwise 
refinement  to  define  the  design  of  a 
large  software  system.  For  one  must 
specify  each  assumption  of  the  next 
lower  level  before  proceeding  to 
that  1 evel . 


4)  By  usinq  a fo rmal  specification, 
one  can  prove  properties  of  the  sys- 
tem specified.  For  instance,  Neu- 
mann, et.al.  (1977)  presents  proofs 
that  their  formally  specified  design 
of  an  operating  system  guarantees 
certain  security  properties  of  the 
system.  Furthermore,  informal 
proofs  of  the  correctness  of  the 


design  can  proceed  at  each  step  of  a 
stepwise  refinement  as  the  desiq n 


5)  With  a formal  specification,  a 


technical  team  using  machine  aids 


could  rigorously  validate  the  design 


before  coding  begins. 


6)  It  has  been  shown  (Parnas, 
1977b)  that  usinq  the  information- 
hiding principle  to  define  modules 
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by  formal  spec i f icat ions  signifi- 
cantly simplifies  the  problems  of 
developing  and  maintaining  embedded 
computer  systems.  An  "embedded  com- 
puter system"  is  a system  developed 
specifically  to  be  a component  of 
another  system.  Such  systems  arise 
in  Defense  Department  needs. 

2.4  Problems  with  formal  specifications  of  modules 

Though  the  formal  specification  of  modules  seems  to 
offer  so  much  in  solving  the  problems  of  large  software 
systems,  there  are  problems  with  using  formal  specifica- 
tions. They  are  very  hard  to  create,  and  therefore 
require  considerable  upfront  investment  of  effort  in  the 
software  development  process.  In  speaking  of  this  up- 
front effort,  Parnas  (1976,  p.  7)  comments,  "The  method 
permits  the  production  of  a broader  family  and  the  com- 
pletion of  various  parts  of  the  system  independently, 
but  at  a significant  cost.  It  usually  pays  to  apply  Jthe 
method  only  when  one  expects  the  eventual  implementation 
of  a wide  selection  of  possible  family  members." 

Each  significant  modification  of  a software  system 
during  its  life  cycle  corresponds  to  moving  from  one 
member  of  the  family  of  software  systems  to  another. 
Consequently,  whenever  it  is  likely  that  significant 
modifications  will  become  necessary  during  the  software 
life  cycle,  a broad  family  of  software  systems  must  be 
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possible  from  the  desiqn.  For  embedded  computer  sys- 
tems, the  likelihood  of  change  throughout  the  life  cycle 
of  the  system  is  particularly  acute. 

2.5  The  need  for  a library 

Thus,  the  technique  of  formal  module  specifications 
seems  to  offer  much  toward  solving  ,y  problems  includ- 
ing: the  high  cost  of  software  maintenance,  the  predomi- 
nance of  design  errors,  the  difficulty  and  cost  of  diag- 
nosing and  correcting  design  errors,  and  the  special 
design  and  maintenance  problems  of  embedded  computer 
systems.  Yet,  the  creating  of  formal  specifications  is 
very  difficult,  requiring  much  upfront  effort,  and 
therefore  the  solution  itself  is  rather  costly. 

The  natural  solution  is  to  develop  a library  of 
formal  specifications  of  modules.  By  reusinq  module 
specifications,  rather  than  recreating  them,  the  cost  of 
the  upfront  effort  would  be  dramatically  cut  and  the 
problems  listed  in  the  preceding  paragraph  would  be 
solved  . 

That  i s the  motivation  of  this  research  in 
ex  am  i n i ng  the  feasibility  of  such  a library.  The  issues 
involved  in  such  a library  beinq  feasible  are  described 
in  the  next  section. 

A library  of  formal  specifications  of  modules  has 
an  additional  benefit  for  design  validation.  If  the 
author  of  a formal  specification  follows  the  guidelines 
for  documentation  that  we  have  developed  during  this 
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research,  each  reader  of  a formal  specification  would  be 
able  to  informally  verify  that  its  specification  satis- 
fies the  properties  the  author  claims  for  it.  There- 
fore, with  each  use  of  a specification  of  the  library, 
our  confidence  in  the  correctne  of  the  specification 
will  justifiably  increase. 

To  answer  each  question  about  the  feasibility  of  a 
library  of  formal  module  specifications,  we  have  g iven 
special  attention  to  techniques  tha  t are  al ready 
available  in  software  practice  and  could  be  adapted  to 
these  pa r ticul ar  questions  regard ing  the  f easib i 1 i ty  of 
a 1 i brar y , (rather  than  spendinq  effort  on  developing 
yet  another  language  or  another  methodology).  Since 
fo  rmal  spec i f icat ions  are  so  hard  to  cr eate  and  demand  a 
way  of  thinking  about  desig  n which  i s rather  new  to  most 
ind iv  idual s , our  focusing  on  familiar  software 
techniques  that  could  be  adapted  to  the  pr ohl ems  of  such 
a 1 ibrary  ha s the  add i t i onal  benef i t of  making  the 


1 ibrary  far  more  practical  and  usable. 
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3 . Issues 

There  are  five  issues  that  must  be  resolved  to 
determine  the  feasibility  of  a library  of  formal  designs 
of  software  modules:  how  to  retrieve  items  from  the 
library,  whether  a few  prototypes  for  a given  applica- 
tion will  cover  the  vast  majority  of  possibilities  for 
that  application,  what  a library  item  should  consist  of, 
whether  the  formal  specifications  will  be  understand- 
able, and  whether  they  can  be  written  in  a way  as  to  be 
easily  modified . 

For  each  of  these  issues,  we  describe  their  signi- 
ficance in  this  section.  Details  of  the  methods  used  in 
answering  these  questions  are  given  in  section  4;  except 
for  the  question  of  retrieval  which  is  answered  in  3.1, 
all  other  questions  are  answered  in  section  5. 

•• 

3.1  Retrieval 

Clearly,  retrieval  from  the  library  is  a crucial 
question;  yet  it  is  a most  difficult  one.  One  class  of 
data  base  techniques  is  oriented  to  storage  and  re- 
trieval of  individual  fields  from  records  satisfying 
particular  properties.  For  instance,  a company  might 
have  a file  of  employee  records  with  one  record  per 
employee,  each  record  consisting  of  fields  such  as  name, 
social  security  number,  address,  birthdate,  department. 


starting  date  with  the  company,  present  salary,  etc. 
Each  field  represents  factual  information  about  the  per- 
son or  entity  represented  by  a record.  Typical 
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retrieval  for  such  a data  base  miqht  include  a command 
such  as  "List  all  employees  in  our  marketinq  department 
who  earn  more  than  $25,000."  There  are  well  defined  and 
researched  technoloqies  for  such  data  bases,  includinq 
relational  data  bases,  hierarchical  ones,  and  CODASYL 
data  bases. 

The  entity  in  question  for  our  library  or  data  base 
is  a module  specification.  Unfortunately,  what  a user 
of  the  library  would  like  to  know  about  one  is  not 
char ac ter i zabl e by  a set  of  facts,  as  in  the  example 
mentioned  above.  Rather,  a deslqner  wants  to  know  the 
function,  purpose,  or  mission  of  a qiven  module  and  see 
what  the  closest  match  to  his/her  need  is. 

This  is  analoqous  to  the  user  of  a library  wantinq 
all  books  or  journal  articles  related  to  a specific  need 
or  topic.  Just  as  in  the  case  of  b ibl ioq raph ic  mater  in 
al , there  is  one  dominant  question:  "Find  all  module 
specifications  (or  books  in  the  b ibl ioq raph ic  case)  that 
address  the  followinq  need  (or  topic  in  the  case  of 
bibl ioqraphic  retrieval)." 

Consequently,  the  relevant  data  base  techniques  are 
those  for  b ibl ioq raph ic  retrieval.  Given  this  analysis, 
we  decided  rather  early  in  the  qrant  period  not  to  in- 
vestiqate  this  question  further  for  the  simple  reason 
that  so  many  people  are  studyinq  the  problem  of  biblio- 
qraphic  retrieval  that  this  effort  would  better  be  spent 
on  issues  solely  related  to  module  specification. 

For  retrieval  purposes, 


------  ■ ■ 


we  therefore  recommend 
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usinq  keywords  to  describe  the  purpose  of  the  module. 

3.2  Prototypes 

Closely  related  to  the  problem  of  retrieval  is  the 
following  crucial  question:  for  any  particular  applica- 
tion need,  will  there  be  a small  number  of  prototypes 
which  cover  most  of  the  variations  possible?  The  ideal 
would  be  that  a handful  of  prototypes  for  a qiven  need 
would  cover  the  major  possibilities,  so  that  the 
designer  can  quickly  ascertain  which,  if  any,  fits  best. 
If  there  are  many  prototypes  necessary  for  each  applica- 
tion, then  the  time  spent  analyzing  each  one  will  make 
using  the  library  prohibitive. 

3. 3 What  to  store 

The  term  "design"  covers  many  aspects  of  software 
devel  opment , ranginq  from  (a!  partitioning  a system  into 
modules  and  precisely  defininq  the  interface  of  each 
module,  to  ( bi  defining  the  detailed  control  structures 
of  a procedure  or  algorithm  using  a program  design 
language.  Of  the  products  which  result  from  the  various 
desiqn  activities,  which  should  be  stored?  Could  all  be 
meaningfully  stored?  Could  programs  implementing  a par- 
ticular design  be  stored  as  well? 

Furthermore,  what  kinds  of  documentation  can  be 
provided  with  each  of  the  prototype  module  designs  so 
that  a user  of  the  library  can  quickly  discard  ones  that 
do  not  fit  his/her  needs  and  concentrate  on  only  a few 
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for  in-depth  study’’ 

3.4  Understandabil ity 

The  formal  designs  stored  must  be  understandable. 
Even  if  the  previous  three  issues  are  satisfactorily 
solved,  a library  of  formal  designs  of  modules  will  be 
useless  unless  the  formal  speci f icat ions  are  understand- 
able. The  user  of  the  library  must  be  ab] e to  under- 
stand the  specifications  in  order  to  decide  whether  the 
design  meets  his/her  needs  and  to  successfully  integrate 
it  into  the  rest  of  the  system  of  which  the  selected 
module  is  a part.  The  module  must  be  integrated  into 
the  system  both  at  the  design  level  and  at  the  implemen- 
tation level. 

Unfortunately,  understandabil i ty  of  formal  design 
specifications  is  the  overwhelming  problem  with  th» 
specification  languages  available.  Consequently,  we 
have  concentrated  most  on  this  one  issue. 

3.5  Modifiability 

Given  that  the  most  appropriate  specification  is 
found,  it  may  not  be  a perfect  match  to  the  designer's 
needs.  In  that  case,  the  more  easily  the  specification 
can  be  modified  to  suit  those  needs  exactly,  the  better. 
What  techniques  are  there  to  write  specifications  which 
are  easily  tailored  to  meet  a slightly  different  need? 


Our  method  has  been  to  specify  as  many  modules  as 
possible  to  build  up  experience  upon  which  to  suqgest 
answers  to  the  five  questions.  Study  of  these  examples 
provides  the  basis  of-  our  conclusions.  The  examples 
fell  into  two  general  classes:  data  structures  and  text 
editors. 

Commonly  used  data  structures  were  chosen  for 
several  reasons.  First,  they  are  crucial  in  virtually 
all  programming  applications;  hence,  they  would  have  to 
be  a part  of  the  proposed  library.  Second,  the 
overwhelming  majority  of  module  specifications  appearing 
in  the  literature  are  just  those  data  structures. 
Third,  they  are  simple  enough  that  we  could  specify 
several  during  the  grant  period;  because  of  their  sim- 
plicity they  would  be  easily  understood  by  anyone  unfam- 
iliar with  the  formal  language  SPECIAL,  (Roubine  and 
Robinson,  197fi),  which  we  used  for  our  specifications. 

Text  editors  were  chosen  because  they  represent  a 
realistically  complex  application  without  being  intract- 
able in  the  time  available. 

For  each  application  considered,  we  tried  to  con- 
ceive of  all  meaningful  variations  that  would  arise 
within  that  application.  Any  significant  difference  in 
the  functional  capabilities  of  the  module  was  considered 
a meaninqful  variation. 

For  a 1 ast- in- f i r st-out  storage  structure,  we 
specified  two  modules:  a stack  from  which  one  could 
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read  values  from  only  the  last  item  stored,  and  a stack 
which  additionally  had  a movable  pointer  into  the  stack. 
Any  value  designated  by  the  pointer  could  be  read,  but 
not  modified.  (This  variation  is  useful  in  interactive 
debugging  aids  to  recursive  programming  languages  such 
as  Algol,  Pascal,  APL,  and  Lisp,  for  the  programmer  can 
then  examine  the  sequence  of  procedure  calls  when  an 
error  occurs.) 

For  a first-in-first-out  storaqe  structure,  we 
specified  four  variations:  a normal  queue  where  reading 
occurs  at  only  the  front  position  of  the  sequence,  a 
priority  queue,  and  two  character  streams.  In  a priori- 
ty queue,  the  first  entered  of  the  larqest  values 
(highest  priority)  is  read  or  removed  from  the  sequence 
before  any  others;  no  other  values  can  be  read.  Charac- 
ter streams  are  very  useful  abstractions  of  input  an»* 
output;  for  they  enable  the  details  of  synchronizing 
input/output  operations  to  be  hidden  in  the  module  rath- 
er than  forcing  all  programs  to  be  aware  of  the  means  of 
synchronization.  The  basic  operation  of  one  of  the 
character  streams  is  character  oriented;  for  the  other 
version,  the  basic  operation  was  oriented  to  blocks  of 
characters  or  lines. 

The  ubiquitous  tree  was  another  application  which 
we  specified.  Two  variations,  the  binary  tree  and  gen- 
eral tree,  seem  to  cover  all  loqical  variations.  Though 
we  specified  a binary  tree,  we  did  not  qet  to  the  gen- 
eral tree.  One  might  wonder  why  a threaded  tree  is  not 


a third  logical  variation.  The  reason  is  simple:  a 
threaded  tree  is  an  implementation  of  a fast  means  of 
performing  tree  traversal,  an  operation  on  trees.  Con- 
sequently, the  specification  of  binary  trees  includes 
three  operations  for  inorder,  postorder,  and  preorder 
traversal;  the  details  of  how  the  traversal  is  performed 
(perhaps  via  thread  links)  is  not  properly  part  of  the 
specification,  for  it  would  violate  the  information- 
hiding principle. 

For  text  editors,  we  found  throe  logical  alterna- 
tives. One  has  operations  oriented  to  adding,  deleting, 
or  moving  characters;  a small,  basic  subset  of  the 
operations  of  TECO,  a popular  editor  on  the  DEC  series 
of  machines,  was  specified.  Another  module  specified 
has  operations  oriented  to  lines  and  line  numbers;  a 
basic  subset  of  the  commands  of  SOS,  another  popular 
editor  on  DEC  machines,  was  specified.  The  third  exam- 
ple is  an  editor  whose  operations  are  oriented  to  moving 
a cursor  on  a CRT  screen  and  editing  on  the  screen;  NED 
(Bilofsky,  1977),  an  editor  running  under  the  UNIX 
operating  system,  was  used  as  a pattern  of  the  function- 
al capabilities  of  such  systems. 

For  each  of  the  modules  specified,  several  tech- 
niques were  used  to  check  the  correctness  of  the  specif- 
ications. (By  "correctness"  of  a specification,  we  mean 
that  it  specifies  exactly  the  properties  desired.)  One 
was  to  use  an  automatic  tool,  the  specification  handler 
for  SPECIAL  (Roubine  and  Robinson,  197fi).  This  checks 
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for  syntactic  correctness  of  a specification.  Since 
SPECIAL  is  a strongly  typed  language  (every  expression 
has  a type  such  as  INTEGER,  BOOLEAN,  etc.),  the  system 
can  check  that  the  types  of  each  expression  always  agree 
with  what  they  should  be.  (Due  to  an  oversight,  the 
priority  queue  was  never  run  through  the  specification 
hand  1 er . ) 

A second  check  was  for  someone  other  than  the  au- 
thor to  scrutinize  the  specification  for  anything  that 
seemed  to  disagree  with  the  author's  claims;  this  is 
like  a walkthrough. 

Third,  a quick  implementation  corresponding  to  the 
prototype  was  made  in  a very  high  level  language  (LISP). 
(An  implementation  of  the  third  text  editor  was  not 
started  due  to  the  termination  date  of  the  grant;  all 
other  modules  were  implemented.)  This  provided  a con*» 
crete  system  for  testing  the  functional  capabilities  of 
the  module;  it  often  uncovered  specification  errors  not 
found  by  the  previous  two  methods.  The  implementations 
took  remarkably  little  time;  by  using  a very  high  level 
language  one  could  trade  the  performance  characteristics 
of  the  implementation  for  vastly  reduced  programmer 
time.  Consequently,  the  final  module  we  checked  in  this 
way  took  only  two  to  three  days  for  one  programmer  to 
implement,  even  though  it  was  the  character-oriented 
text  editor,  a significant,  realistically  complex 
module.  Furthermore,  we  found  significant  regularity  in 
the  implementation  of  most  types  of  expressions 
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specified  In  SPECIAL.  This  suggests  that  a significant 
proportion  of  each  implementation  could  be  done  automat- 
ically  by  a software  tool. 


-2  9- 


5 . De  t a i l ed  resul ts 

In  section  3,  we  isolated  five  questions  about  the 
feasibility  of  a library  of  formal  desiqns  of  software 
modules.  Section  4 presented  the  empirical  study  per- 
formed to  answer  the  questions.  One  question,  how  to 
retrieve  items  from  such  a library,  was  answered  in  sec- 
tion 3.  Our  results  on  the  remaining  questions  are 
detailed  here. 

5. 1 Prototypes 

For  any  particular  application,  will  a handful  of 
prototypes  cover  most  of  the  possible  modules  to  meet 
that  need?  If  more  than  a handful  are  needed  for  any 
particular  need,  the  desiqner  will  have  to  spend  too 
much  time  analyzing  each  one  to  find  the  best  .for 
his/her  needs. 

Our  experience  in  writinq  many  specifications  is 
very  encouraging;  however,  it  is  simply  insufficient  to 
answer  the  question  conclusively. 

In  the,  area  of  data  structures,  two  to  four  proto- 
types seem  sufficient  to  cover  the  various  significant 
alternatives.  For  instance,  for  a stack,  or  last-in- 
first-out  storage  structure,  the  two  alternatives  were  a 
stack  allowing  retrieval  of  values  only  at  one  place 
(the  "top")  and  a stack  allowing  retrieval  of  values 
from  any  position  designated  by  a movable  pointer. 

Although  certain  details  of  each  specification 
might  be  changed  by  the  desiqner,  details  such  as 
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whether  trying  to  read  from  an  empty  stack  causes  an 
error  or  not,  are  not  significant  enough  to  warrant 
storing  additional  prototypes.  Rather,  the  author  of 
the  specification  in  the  library  can  include  in  the 
documentation  notes  to  the  readers  (designers)  about 
details  that  might  be  modified.  In  fact,  our  documenta- 
tion for  each  example  includes  that. 

In  addition  to  the  area  of  data  structures,  our 
examples  dealt  with  medium-sized  software  tools,  such  as 
text  editors.  (By  software  tools,  we  mean  software  that 
serves  as  an  aid  in  writing  other  software.)  Though 
there  was  only  enough  time  to  study  the  one  application 
area  of  text  editors,  our  experience  was  very  encourag- 
ing. Thus,  we  cannot  state  conclusively  that  for  all 
classes  of  software  tools,  a handful  of  prototypes  will 
largely  cover  all  variations,  but  we  suspect  that  thi& 
will  hold  true. 

For  instance,  there  are  a vast  variety  of  text  edi- 
tors available.  However,  they  seem  to  be  classifiable 
into  three  categories.  The  first  category  is  text  edi- 
tors whose  operations  are  oriented  to  insertion  and 
deletion  of  characters  relative  to  a current  position. 
Line  numbers  may  not  be  used  at  all;  rather,  one  moves 
the  pointer  defining  the  current  position  to  indicate 
where  editing  is  to  occur.  TECO  (Digital  Equipment  Cor- 
poration, 1972),  a DEC  product,  is  an  example  of  this 
class.  The  second  category  is  text  editors  whose  opera- 
tions have  a sequence  of  line  numbers  as  an  argument  and 
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which  are  therefore  oriented  to  operations  on  lines. 
SOS  (National  Institute  of  Health,  1977),  another  DEC 
product,  is  a particularly  rich  example  of  this  class  in 
that  the  user  may  leave  the  line-oriented  mode  and  move 
to  a character-oriented  mode  on  a ranqe  of  lines.  The 
third-  category  is  text  editors  whose  operations  are 
based  on  viewing  a CRT  screen  as  a window  into  the  file, 
where  editing  can  take  place.  Editing  occurs  within  the 
window  relative  to  the  position  of  a cursor.  NED  ( B i — 
lofsky,  1976),  is  an  example. 

Almost  all  general-purpose  text  editors  can  be 
classified  into  one  of  the  three  categories.  (One  ex- 
ception is  the  special-purpose  editors  created  for  edit- 
ing LISP  programs  (Sandewall,  1978).)  However,  that 
does  not  prove  that  three  prototypes  will  cover  most 
appl  ications , unless  one  follows  these  principles  i*v 
creating  the  specifications  for  the  library. 

1)  Certain  details  of  a specification 
will  vary  given  the  environment  in  which 
the  module  is  to  be  used.  Select  a con- 
sistent set  of  decisions  for  the  specifi- 
cation in  the  library.  As  much  as  is  pos- 
sible, localize  each  such  detailed  deci- 
sion in  a subdefinition  of  the  specifica- 
tion; in  this  way,  a user  of  the  library 
can  modify  the  arbitrarily  chosen  detail 
just  by  changing  the  subdefinition.  (One 
of  the  extremely  useful  features  of 
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SPECIAL  is  that  the  lanquage  provides  many 
mechanisms  for  making  such  subdefini- 
tions.) In  the  documentation,  ail  details 
which  are  arguable  must  be  clearly  indi- 
cated . 

2)  In  specifying  a new  entry  for  the 
library,  avoid  differences  that  are  not 
fundamental  to  the  logical,  functional 
capabilities  of  the  module.  Those  differ- 
ences would  multiply  the  number  of  entries 
for  a given  application  in  the  library 
without  adding  any  new  abilities.  For 
instance,  in  specifying  text  editors,  we 
did  not  define  a user  command  language, 
for  there  are  many  legitimate  syntactic 
variations,  each  of  which  will  be  of  vary- 
ing value  to  different  user  communities. 

3)  The  author  of  a new  entry  for  the 
library  should  specify  as  many  logically 
different,  primitive  operations  as  can  be 
imagined.  A designer,  after  selecting  a 
specification  from  the  library,  can  delete 
operations  from  the  interface  not  needed 
in  his/her  environment.  This,  of  course, 
assumes  that  each  operation  at  the  inter- 
face was  defined  using  information-hiding 
as  stated  in  principle  (1).  For  instance. 
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our  specification  of  a line-oriented  edi- 
tor was  patterned  after  the  functional 
capabilities  of  SOS.  The  operations 
corresponding  to  the  alter  mode,  where  the 
user  can  modify  a range  of  lines  using 
character-oriented  operations  relative  to 
a pointer,  can  easily  be  removed. 

In  conclusion,  our  experience  is  too  limited  to 
determine  whether  for  all  applications,  only  a handful 
of  prototype  specifications  will  cover  almost  all  varia- 
tions in  modules  for  the  particular  application.  Howev- 
er, the  three  principles  above  did  enable  us  to  specify 
a handful  of  prototypes  successfully  covering  most  anti- 
cipated needs  in  the  application  area  of  text  editors 
and  in  the  class  of  applications  of  data  structures. 
That  fact  is  quite  encouraqinq. 

5.2  What  to  store 

For  any  given  module  specification  to  be  added  to 
the  library,  what  should  be  stored?  The  functional 
specification?  A hierarchical  design  for  implementing 
the  module?  A complete  program?  Furthermore,  what 
kinds  of  documentation  are  necessary? 

Clearly,  the  abstract,  formal  specification  of  the 
interface  of  the  module  must  be  stored,  for  this  is  cen- 
tral to  hierarchical  design  of  a large  software  system. 
The  specification  of  the  module's  interface  defines  each 
functional  capability  of  the  module,  specifying  the 


-34- 


arguments  of  each  function  call,  and  the  effect  of  any 
operation  or  function  at  the  interface  of  the  module. 
Of  course,  this  information  is  exactly  what  is  necessary 
for  the  independent  implementation  and  use  of  modules 
according  to  the  information-hiding  principle  (Parnas, 

k- 

1972).  Furthermore,  the  specification  of  the  module 
interfaces  is  necessary  for  embedded  computer  systems. 

Thus,  the  formal  specification  of  the  module's 
interface  must  be  included,  and  we  have  therefore  con- 
centrated our  research  on  this.  Yet,  could  one  store  an 
implementation  as  well?  In  general,  any  module  of  sig- 
nificant size,  when  implemented  would  itself  be 
hierarchically  broken  down  into  modules  that  together 
implement  it.  Furthermore,  there  would  normally  be 
several  alternate  ways  of  hierarchically  defining 
modules  to  implement  the  one  of  interest.  Thus,  once 
the  designer  has  selected  a module  specification  meeting 
his/her  needs,  a second  selection  must  be  made  from 
several  alternate  hierarchical  designs  implementing  the 
module.  There  is  no  technical  problem  to  being  able  to 
specify  the  hierarchy,  for  SPECIAL,  as  with  other 
specification  languages,  permits  the  formal  definition 
of  a hierarchy  implementing  the  functional  capabilities 
of  a module  as  well  as  the  formal  definition  of  those 
functional  capabilities. 

The  diagram  below  summarizes  this.  Associated  with 
each  module  specification  M,  there  would  be  a few 
hierarchical  designs  HD  for  implementing  it. 
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It  is  possible  technically;  however,  the  designer 
must  consider  each  alternative  design  after  selecting  a 
given  module.  The  true  payoff  would  come  if  not  only 
the  hierarchical  design  could  be  stored  but  also  pro- 
grams corresponding  to  it. 

Again,  even  for  a single  hierarchical  design,  there 
will  in  general  be  several  significant,  alternate  pro- 
grams implementing  it.  Given  a module's  specification, 
the  differing  hierarchical  designs  for  it  and  the  vari- 
ous programs  implementing  each  design  will  offer  various 
tradeoffs  in  computing  time  required,  memory  used,  and 
other  computer  resources  required.  In  other  words,  th'd 
performance  and  computational  needs  of  the  various  pro- 
grams make  the  alternatives  meaningfully  different.  As 
an  example  of  this,  even  for  a task  as  simple  as  sorting 
a sequence  of  items,  there  are  several  competing  algo- 
rithms, such  as  quicksort,  heapsort,  merqesort,  bub- 
blesort,  and  insertion  sort.  Each  has  advantages  and 
disadvantages  due  to  differing  performance  and  memory 
requirements.  Given  the  env i ronment , the  tradeoffs 
among  the  algorithms  can  be  resolved  to  select  a partic- 
ular program.  Thus,  we  have  the  situation  described  in 
the  figure  below.  For  each  module  M,  there  will  be  a 
few  associated  hierarchical  designs  HD. 
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It  is  technically  feasible  to  include  with  the 

functional  specification  of  the  module's  interface  vari- 

/ 

ous  hierarchical  designs  and  corresponding  programs 
implementing  the  module.  However,  since  the  number  of 
implementations  that  may  need  to  be  stored  for  any 
module  could  be  relatively  large,  developing  a reason- 
ably complete  library  including  implementations  as  well 

could  take  many  years.  However,  the  library  would  be  of 

/ 

great  value  to  designers  just  with  the  module  interface 
specifications  as  the  alternative  programs  for  each 
module  are  added  slowly. 

Furthermore,  even  with  a complete  library,  some 
reprogramming  would  always  be  necessary.  The  reason  is 
that  the  module  specification  M itself  may  oftentimes 
need  slight  modification  due  to  varying  environments  in 
which  the  module  is  to  be  used.  This  will  require 
modification  of  one  of  the  library's  programs 
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implementing  it  as  well.  For  this  to  be  feasible,  each 
program  stored  would  have  to  be  very  well  structured  and 
very  well  documented. 

To  repeat,  in  this  study  we  have  concentrated  ex- 
clusively on  the  feasibility  of  building  a library  of 
module  specifications  M,  defining  the  interface  of  a 
modul  e. 

What  documentation  must  be  stored  with  these  module 
specifications  M?  Detailed  documentation  must  be  stored 
in  the  formal  specification  itself  so  that  a comment  is 
with  the  expression  it  is  describing.  Our  thoughts  on 
such  commenting  appear  in  section  5.3.  Additionally,  a 
short  high-level  description  is  crucial  to  the  effec- 
tiveness of  the  library  so  that  the  designer  may  quickly 
ascertain  whether  a module  specification  is  relevant  to 
his/her  needs.  The  designer  must  be  able  to  quickly 
eliminate  ones  that  are  not  close  to  the  need  so  that 
he/she  can  focus  attention  on  two  or  three  that  are  the 
most  promising.  Otherwise,  the  library  would  bog 
designers  down  on  decisions  that  should  be  made  quickly. 

We  have  found  six  types  of  information  that  seem 
valuable  for  quickly  deciding  on  the  relevance  of  a 
module  specification.  One  is  a list  of  keywords 
describing  the  purpose  of  a module.  A second  item  is  a 
description  of  the  purpose  of  the  module  and  the  kinds 
of  needs  it  fills.  A third  item  is  a summary  descrip- 
tion of  each  class  of  functional  capabilities  the  system 
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Fourth,  the  kinds  of  decisions  not  made  by  the 
module  are  described;  these  are  implementation  decisions 
which  would  have  to  be  made  after  selecting  a module, 
when  the  codinq  phase  begins.  These  decisions,  which 
are  left  open  by  the  specification  of  the  module's  in- 
terface, are  a direct  measure  of  how  easily  the  software 
can  be  modified  during  its  life  cycle.  This  is  because 
the  decision  is  made  at  implementation  rather  than  at 
design,  and  because  the  result  of  the  decision  is  iso- 
lated in  one  module.  Therefore,  each  decision  is  easily 
reversed  during  the  system’s  life  cycle  by  modifying 
only  the  one  module  (rather  than  having  to  modify  many). 
For  instance,  in  specifying  a text  editor,  we  would 
write  in  this  section,  (which  we  have  called  "Informa- 
tion Hidden"),  that  a decision  to  use  array  storage, 
linked  lists,  or  other  alternatives  to  store  the  file 
beinq  edited,  would  have  to  be  made  when  programming  of 
this  module  begins. 

Fifth,  specific  references,  such  as  texts  and  jour- 
nals, if  available,  should  be  given  describing  various 
implementations,  algorithms,  and  analyses  of  them  for 
use  when  programming  begins.  And  last,  the  author  of 
the  specification  must  include  all  ways  that  he/she 
anticipates  that  the  specification  might  require  modifi- 
cation to  tailor  it  to  specific  needs.  Of  course,  some 
details  of  the  specification  will  be  rather  arbitrary; 
these  must  be  pointed  out  so  that  one  specification  can 
serve  for  many  slight  variations. 
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5.3  Understandabil ity 

The  formal  specification  of  a module  M must  be 
understandable  if  it  is  to  achieve  its  purpose,  for  it 
acts  as  a contract  between  designers  and  programming 
team,  statinq  exactly  what  the  programming  team's  pro- 
duct must  do  (Parnas,  1977a) . If  a contract  cannot  be 
understood,  it  serves  no  purpose.  However,  the  under- 
standability  of  formal  specifications  in  a library  be- 
comes even  more  crucial,  for  if  the  designer  cannot 
understand  the  alternative  specifications,  how  can  an 
intelligent  choice  be  made  amonq  the  alternatives?  Con- 
sequently, our  research  has  concentrated  most  on  this 
single  question. 

Our  results  are  in  two  parts:  reasons  why  formal 
specifications  have  been  difficult  to  understand  .and 
specific  suggestions  on  making  them  understandable. 
Researchers  in  the  area  of  formal  module  specifications 
and  abstract  data  types  generally  agree  that  they  are 
difficult  to  understand,  though  the  deqree  of  difficulty 
is  argued. 

We  have  found  several  reasons  for  the  difficulty  of 
understanding  formal  specifications,  particularly  as 
compared  to  natural  language  specifications. 


reason 


that 


natural 
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inappropr iate  for  module  specification, 
the  necessary,  added  detail  in  a formal 
speci f ication  makes  them  harder  to 
understand . Liskov  (1977>  agrees,  statinq 
on  p.  13-5,  "Rigorous  informal  specifica- 
tions  are  probably  just  as  difficult  to 
construct  as  formal  ones;  informal  specif- 
ications appear  easier  to  construct  be- 
cause they  are  usually  incomplete." 

ii)  Natural  language  is  used  by  each  per- 
son daily;  thus,  a natural  language 
speci f ication  has  myr iads  of  concepts 
al ready  defined  and  f ami 1 iar  to  us  to 
succ inctl y state  what  a modul e does . For 
example,  the  concepts  of  a sorted  se- 
quence, a pointer,  and  a line  of  text,  are 
all  well-known  and  are  referred  to  without 
further  explanation.  (Yet,  the  advantage 
this  gives  to  understandabil ity  is  simul- 
taneously a serious  drawback  to  natural 
language  specifications,  since  the  notion 
raised  in  each  person's  mind  need  not  be 
the  same.^  Because  fo rmal  specifications 
are  so  new,  there  is  no  correspo nd ing  body 
of  defined  concept?-,  which  have  been  taught 
us  and  which  have  been  f r equentl y used  by 
us.  Therefore,  concepts  such  as  sorted 
order  must  be  defined  in  the 
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specification,  thus  addinq  to  what  must  be 
understood  in  the  spec i f icat ion . Of 
course,  a library  of  such  definitions 
would  provide  a body  of  past  experience  to 
study  and  use  just  as  in  natural  lanquaqe. 
The  formal  definitions  are  unambiquous  and 
precise;  therefore  the  definitions  do  not 
allow  multiple,  valid  interpretations  as 
in  natural  lanquaqe. 

iii)  Formal  spec  i f icat  ions  of  modules  are 
to  be  abstract  and  cover  many  possible 
implementations.  Not  only  does  the 
abstractness  itself  contribute  to  qreater 
difficulty  in  understandabil ity , but  the 
semantics  of  the  abstract  lanquaqes  is 
necessarily  quite  different  than  the  se- 
mantics of  proqramming  languages,  since 
programming  languages  are  designed  to 
define  implementation  detail.  Thus,  the 
focus  of  attention  of  specification 
lanquaqes  is  of  necessity  quite  different 
from  programming  languages.  Therefore  the 
semantics  of  specification  lanquaqes  i s 
qu i te  different  than  programmers  are  used 
to . 


The  following  specific  suggestions  for  making  for- 
mal specifications  understandabl e have  come  out  of  our 
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research.  There  are  two  alternate  approaches  one  could 
take  to  make  formal  specifications  more  understandable. 
One  would  he  to  abandon  the  present  specification 
lanquaqes  and  try  to  formulate  one  whose  semantics  is 
like  that  of  standard  proqramminq  lanquaqes.  Yet,  as 
(iiil  states,  that  would  fail  since  specification 
lanquaqes,  because  of  their  purpose,  must  have  a seman- 
tics different  than  proqramminq  lanquaqes.  A second 
approach  i s to  adapt  the  techniques  fo r organizing 
clear , understandable  prog  ram  code  to  the  pr obi em  of 
wr i t i nq  understandabl e fo rmal  spec! f icatlons;  this  is 
the  approach  we  have  taken. 

Therefore,  the  suggestions  are  familiar  in  program- 
ming. Our  suqgest ions , rather  than  being  platitudes, 
such  as  "Use  comments,"  are  specific  guidelines,  such  as 
when  to  include  a comment  and  what  to  write.  Only  » 
summary  of  the  guidelines  are  presented  in  this  section. 
Fully  specified  modules  usinq  these  guidelines  are 
presented  in  Appendices  TI  throuqh  V and  also  in 
Weischedel  (1979). 

The  test  of  these  guidelines  is  whether  the  module 
specifications  seem  understandable  to  the  reader  given  a 
reasonable  amount  of  study  and  some  familiarity  with  the 
specification  language  SPECIAL.  (A  brief  description  of 
the  major  features  of  SPECIAL  is  presented  in  Appendix 
I).  Appendix  II  specifies  a stack;  appendix  III,  a 
queue,  and  appendix  IV  a binary  tree.  Appendix  V is  one 
of  the  three  text  editors  specified.  The  examples  of  a 


stack  and  a queue 
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are  intended  to  provide  short,  simple 
cases  of  familiar  concepts  to  aid  becoming  familiar  with 
SPECIAL. 


Our  guidelines  are  as  follows: 

1)  Since  the  specification  languages,  being 
abstract  and  nonprocedural,  have  a semantics  very  dif- 
ferent from  that  of  most  programming  languages,  one 
should  choose  a speci f ication  language  whose  semantics 
draws  on  concepts  common  i n programming . For  instance, 
one  of  the  strong  points  of  SPECIAL  is  the  familiarity 
of  many  of  its  primitive  concepts,  including  functions, 
arguments  of  a function,  exception  conditions,  side 
effects,  declarations,  records,  sets,  vectors,  reals, 
integers,  and  characters. 

7)  English  documentation  should  be  pa instaki ngly 
constructed  with  the  following  principles  in  mind:  - 


a)  A high  level  description  of  the 
purpose  of  a module  which  is  formally 
specified  and  a description  of  each 
function  available  at  the  interface  of 
the  module  provides  a general  notion 
or  conceptualization  for  understanding 
the  formal  specification.  Though  that 
description  will  be  vague,  incomplete, 
and  ambiguous,  it  conveys  a toplevel 
view  around  which  the  complete,  unam- 
biguous, precise  formal  description 
can  crystallize  into  under  stand ing  in 


-44- 


1 


the  reader’s  mind.  Of  course,  the 
formal  spec  i f icat. ion  alone  is  the 
arbiter  of  all  questions  about  the 
module.  Such  a hiqh  level  description 
is  essential  documentation  for  manage- 
ment personnel  . 

b)  In  general,  formal  specifications 
will  consist  of  a large  number  of  for- 
mulas, some  of  which  can  be  very  long. 
(Consider  the  examples  in  the  appen- 
dices and  in  Weischedel  (1979).)  Each 
formula  should  be  documented,  prefer- 
ably with  the  documentation  intermixed 
in  the  formulas,  so  that  the  purpose 
and  implications  of  each  subformula 
are  made  obvious.  The  reason  is  sim- 
ple: the  author  of  the  specification 

when  writing  down  a long  formula  had 
specific  reasons  for  writing  each  sub- 
formula. Those  reasons  or  implica- 
tions should  be  succinctly  stated. 
The  principle  fo  r dec  id ing  whether  to 
include  a comment  for  a par ticul ar 
suhformul  a i s whether  its  purpose  and 
impl icat ions  would  be  obvious  to  the 
average  read er  wi thout  a comment.  To 
illustrate  this,  figure  1 is  given  as 
a definition  of  a function  sort  which 
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returns  a sequence  b in  ascend inq  ord- 
er correspond inq  to  the  input  sequence 
a.  Comments  are  preceded  by  a dollar 
sign  and  are  enclosed  within 
parentheses.  Reserved  words  of 
SPECIAL  are  typed  in  upper  case.  The 
comments  qenerated  by  following  this 
principle  probably  enable  most  readers 


to 

undei 

r stand 

and 

verify  the 

spec 

i f i — 

cat 

ion 

even 

without  knowing 

the 

de- 

ta  i 

led 

syn tax 

or 

semantics 

o f 

the 

spe 

cification 

1 anq 

uaqe. 

c) 

Not 

only  will 

foil owi nq 

(a) 

and 

(b)  make  formal  specifications  under- 
standable, but  also  following  them 
gives  each  reader  of  the  specification 
the  ability  to  verify  that  every  as- 
pect and  subformula  of  it  corresponds 
to  the  author's  intent.  This  is  an 
informal  means  of  design  validation; 
for  a library  of  such  specifications, 
the  means  is  very  powerful  since  more 
and  more  designers  will  be  reading  and 
verifying  a specification  as  time  goes 
by. 


■M 


■ ■■ 


VF UN  sort  (VECTOR  OF  REAL  a)  ->  VECTOR_OF  REAL  b; 
$(Given  a sequence  of  real  numbers  a,  a sorted 
sequence  of  the  same  numbers  is  returned  as  b in 
ascending  order.) 


DERIVATION 

SOME  VECTOR_OF  REAL  bl 

$ (b  is  the  permutation  of  a) 

LENGTH  (b) -LENGTH  (a)  AND 

(FORALL  REAL  xl (EXISTS  INTEGER  i :x  = a[il) 

$(For  every  value  x of  the  original  sequence, 
the  following  is  true)  .. 

: CARDINALITY  ({INTEGER  j|a(jl=xt) 

-CARDINALITY  ({INTEGER  k|b[kl=x})) 

S (The  same  number  of  copies  of  x are  in  the 
original  sequence  a as  in  the  resultant 
sequence  b) 

AND  $(b  is  in  ascending  order) 

(FORALL  INTEGER  i|(l<=i  AND  i <LENGTH (b) ) 

: b { i 1 <=b[ i+11 ); 


' I 


Figure  1 
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(The  reader  may  be  tempted  to  conclude  that  our 
guidelines  on  documentation  are  obvious.  The  two  most 
significant,  most  impressive  uses  of  formal  specifica- 
tions in  designing  large  systems  are  Neumann,  et.al. 
(1977)  and  Ford  Aerospace  (1978),  botu  specifying  secure 
operating  system  designs.  Neither  uses  comments  to  the 
degree  we  have  advocated,  and  we  feel  that  both  would  be 
considerably  more  understandable  if  comments  were  added 
using  our  guidelines.  Some  computer  scientists,  in 
fact,  would  disagree  with  our  guidelines  for  using  com- 
ments, feeling  that  such  comments  bias  the  interpreta- 
tion of  the  specification  or  weaken  it  somehow.  For 
instance,  one  referee  of  an  early  version  of  Weischedel 
(1979)  wrote,  "The  English  descriptions  play  too  central 
a role."  Clearly,  then,  our  guidelines  are  not  obvious. 
We  have  concluded  that  without  these  guidelines,  format1 
specifications  of  large  systems  are  almost  impossible  to 
understand.  Of  course,  they  do  suggest  an  interpreta- 
tion, one  that  is  critical  to  understanding  a formal 
specification  and  which  is  valuable  for  informal  verifi- 
cation that  it  specifies  what  the  author  intended. 
Without  such  documentation  there  is  just  as  much  chance 
for  misinterpretation  of  the  specification,  plus  the 
added  drawback  that  they  would  net  be  understandable. 
The  depth  of  documentation  espoused  here  and  the  practi- 
cal principle  for  deciding  whether  to  include  a comment 
is  a practical  contribution  of  our  research.) 

3)  There  are  several  styles  of  writing  even  simple 


STRUCT  OF  (INTEGER  namel;  CHAR  name2)  defines  records 
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formal  specifications.  Sometimes  a simple  composition 
of  the  primitive  elements  of  the  language  suffices  to 
define  a concept.  Recursive  definitions  can  provide 
short,  easy  to  understand  specifications.  Another  al- 
ternative is  to  use  the  English  definition  of  the  object 
as  a pattern  for  a formal  definition;  this  often  leads 
to  definitions  in  terms  of  sets  and  operations  on  them. 
In  writing  the  specifications  for  our  library,  we  have 
found  that  the  styl e that  seems  clearest  depend s on  the 
item  being  defined . Understandabil ity  of  the  formal 
specifications  should  be  an  explicit  goal  of  the  design 
phase.  Since  there  are  several  styles  of  definition 
that  may  be  used,  walkthroughs  were  used  by  us  to  check 
not  only  the  correctness  of  a specification  but  al so  its 
understandabil ity . For  the  three  text  editors  we  have 
specified,  walkthroughs  proved  very  valuable  in  criti** 
cizing  both  the  formal  definitions  and  the  documenta- 
tion. Understandabil ity  is  not  easily  attained.  For 
each  of  the  text  editors,  after  completely  specifying 
one,  we  were  able  to  conceive  of  a much  more  understand- 
able, but  functionally  equivalent  specification  by  sig- 
nificantly changing  the  style  of  the  definitions.  We 
have  concluded  that  entries  fo r library  of  fo rmal 
modul e sped  f ications  should  be  prepared  wi  th  so  much 
care  for  understandabil ity  that  casting  away  the  first 
attempt  at  a speci f ication  to  create  a more 
understandabl e one  i s not  frowned  upon.  Writing  clear 
nonfiction  receives  that  much  attention;  so  should 
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creatinq  a specification  to  reside  in  a library  of 
module  specifications  for  repeated  use. 

4)  In  (ii)  it  was  stated  that  one  reason  that  for- 
mal specifications  are  harder  to  understand  than  Enqlish 
ones  if  the  abundanceof  concepts  already  defined  in 
Enqlish,  but  which  have  yet  to  be  defined  in  formal 
lanquaqes.  Therefore,  in  Enqlish  specifications,  the 
concepts  may  simply  be  referred  to  whereas  in  formal 
specifications  each  concept  must  be  defined.  This  leads 
to  three  natural  conclusions:  (a)  a library  will  add  to 
the  understandabil i ty  of  formal  specifications  as  the 
definitions  in  the  library  become  familiar  to  desiqners, 

( b)  until  such  a library  is  built  up,  module  specifica- 
tions will  be  rather  complex  as  all  concepts  must  be 
explicitly  defined  in  a top-down  way,  and  (c)  -the 
specification  lanquaqe  should  provide  a rich  set  of 
primitive  obiects  and  operations  on  them  to  alleviate 
the  lack  of  concepts  previously  defined.  The  example  of 
fiqure  1 illustrates  this;  the  definition  would  be  much 
shorter  and  clearer  if  a concept  permutation ( a ,bl  were 
already  defined  in  the  lanquaqe  or  in  the  library.  For 
that  matter,  the  concept  of  a sorted  sequence  is  so  com- 
mon, that  its  precise  definition  should  be  primitive  to 
the  specification  lanquaqe. 

While  we  have  not  invented  "new"  ideas  for  under- 
standabil ity  , we  have  demonstrated  that  formal  specifi- 
cations can  be  made  far  more  understandable  iust  by 
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using many  of  the  ideas  espoused  in  structured  program- 
ming. The  reader  is  invited  to  check  this  claim  by  com- 
paring our  specifications  in  the  appendices  and  in 
Weischedel  (1979)  with  those  of  other  authors. 


5.4  Modifiability 

Can  the  prototype  in  the  library  be  made  modifiable 
enough  so  that  minor  changes  can  be  made  to  tailor  a 
specification  to  a specific  environment"7  There  are  two 
simple  techniques  that  we  suggest  which  will  make 
specifications  in  the  library  rather  modifiable. 

The  first  is  to  structure  the  definitions  of  each 
function  at  the  interface  of  a module  so  that  each  par- 
ticular detail  that  might  need  modification  is  localized 
in  only  one  subdefinition.  Then  only  one  subdefinition 
need  be  changed  rather  than  the  changes  being  spread 
throughout  the  specification.  (This  is  just  the 
information-hiding  principle  being  applied  to  writing 
definitions  in  a specification  language  rather  than  its 
original  application  as  a criterion  for  decomposing 
large  systems  into  modules.)  One  of  the  nice  features 
of  SPECIAL  is  that  several  mechanisms  are  provided  in 
the  language  for  making  subdefinitions.  In  addition  to 
the  ability  to  reference  functions  at  the  interface  of 
other  modules,  one  can  create  subdefinitions  within  a 
single  module  purely  to  localize  information  that  might 
be  changed  in  the  module's  definition.  One  method  is 
the  DEFINITIONS  feature  for  defining  particular 
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subformulas  of  significance.  Another  is  the  TYPES 
feature  for  defining  a complex  new  data  type  used  as 
arguments  to  functions. 

A particularly  good  example  of  this  appears  in 
Weischedel  (1979)  where  a formal  specification  is  given 
for  an  unusually  sophisticated  pattern  matching  feature 
for  searching  a file.  In  applying  the  principle,  the 
toplevel  specification  of  the  search  feature  precisely 
defined  the  lines  that  would  be  found  and  that  those 
lines  would  be  returned  in  order  of  appearance  in  the 
file.  The  syntax  of  the  pattern  language,  and  therefore 
what  it  meant  for  the  search  procedure  to  detect  an 
illegal  pattern,  was  defined  in  a subdefinition  lower 
than  the  toplevel.  The  semantics  of  the  pattern 
language  was  also  localized  in  a subdefinition.  There- 
fore, both  the  syntax  and  the  semantics  of  the  pattern 
language  for  the  search  could  easily  be  modified  for 
different  user  environments. 

The  second  idea  was  mentioned  earlier.  Namely,  the 
author  of  the  speci f ication  can  anticipate  many  poten- 
tial modifications  merely  by  analyzing  what  details  of 
the  specification  are  somewhat  arbitrary  (in  that  the 
details  will  vary  depending  on  the  environment  in  which 
the  module  is  to  be  used).  The  author  can  list  each 
detail  which  might  need  modification  as  an  integeral 
part  of  the  documentation.  As  an  example,  consider  a 
queue.  In  a sequential  programming  environment,  an 


attempt  to  remove  an  item  from  an  empty  queue  is  an 
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error.  However,  in  a multiprocessing  environment,  such 
a condition  is  merely  a siqnal  that  the  process  request- 
ing information  should  be  suspended  until  some  other 
process  adds  something  to  the  queue. 

These  two  simple  principles  will  make  the  proto- 
types in  the  library  rather  modifiable. 
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6.  Related  Work 

There  are  several  areas  of  related  work.  The 
first,  of  course,  is  research  in  a design  methodology 
using  the  information-hiding  principle.  Parnas  (197*) 
demonstrates  how  modularization  of  the  type  assumed  here 
can  be  used  to  define  a family  of  closely  related 
software  systems,  thus  making  maintenance  and  modifica- 
tion of  software  during  their  life  cycle  much  easier. 
Parnas  (1977b)  shows  the  relation  of  formal  specifica- 
tions of  modules  to  the  special  problems  of  embedded 
computer  systems.  Neumann  (19^7)  and  Ford  Aerospace 
(1978)  are  the  most  significant  systems  designed  to  date 
using  formal  specification;  both  are  operating  systems 
whose  designs  have  been  formally  proved  to  maintain 
security. 

A second,  related  area  is  research  in  specification 
languages  to  support  defining  a module's  interface  in- 
dependent of  its  implementation.  This  is  frequently 
referred  to  as  abstract  data  types  in  the  literature. 
Liskov  and  Berzins  (1977)  provide  a survey  of  this 
research.  Ambler,  et.al.  (1977)  presents  a specifica- 
tion language  which  is  very  similar  in  semantics  to  the 
one  we  have  used.  Algebraic  languages  have  the  same 
purpose,  though  having  a quite  different  semantics. 
Examples  are  presented  in  Guttag,  et.al.  (1978)  and  Par- 
nas (1977b).  Yet,  a third  class  of  specification 
languages  is  represented  in  the  ideas  of  Balzer  and 
Goldman  (1979) . 
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A third  related  area  of  work  is  the  National 
Software  Works  (NSW)  reported  in  Crocker  (1975).  NSW  is 
a library  of  software  tools  available  on  the  ARPA  net. 
A software  tool  is  a software  system  used  in  the 
development  of  other  software;  examples  include  editors, 
compilers,  interactive  debugging  aids,  simulators,  docu- 
ment formatters,  program  verifiers,  and  automatic  test 
case  generators.  The  purpose  of  NSW  is  to  enable  pro- 
grammers to  use  software  tools  via  the  ARPA  network, 
tools  which  would  otherwise  be  unavailable  to  them.  The 
reason  software  tools  would  be  unavailable  otherwise  is 
threefold:  (a)  the  traditional  dependence  of  software 
on  a particular  computer  and  operating  system,  (b)  the 
lack  of  facilities,  such  as  sufficient  memory  or  in- 
teractive systems,  at  the  geographical  site  of  the  pro- 
grammer, and  (c)  the  expense  of  obtaining  proprietary 
software.  Thus,  it  shares  the  notion  of  a library  to 
aid  software  development;  yet,  its  purpose  is  quite  dif- 
ferent. Its  purpose  is  to  make  the  execution  of 
software  tools  available  to  programmers.  The  purpose  of 
a library  as  we  have  envisioned  is  to  make  the  formal 
specifications  of  module  interfaces  available  to 
designers  for  reuse  in  developing  new  software.  Formal 
specifications  from  such  a library  would  enable  discip- 
lined design  of  large  systems  and  rigorous  design  vali- 
dation by  a validation  team. 


I 
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Appendix  I 

This  section  is  written  to  help  the  reader  under- 
stand a specification  written  in  SPECIAL  (SPECIf ication 
and  Assertion  Language)  Roubine  and  Robinson,  (1976). 
The  discussion  of  SPECIAL  will  not  encompass  all  of  the 
language's  features.  The  explanation  is  intended  as  a 
guide  in  understanding  the  examples  which  accompany  this 
report. 

The  design  of  a large  software  system  requires 
breaking  the  system  into  component  parts  called  modules. 
Parnas  (1972)  describes  a criterion  called  the 
information-hiding  principle  for  deciding  how  to  decom- 
pose a system  into  modules.  According  to  this  design 
principle,  any  decision  which  may  need  to  be  modified 
during  the  system's  life  cycle  should  be  localized  in  a 
single  module.  In  that  way,  if  the  results  of  any  deci- 
sion implemented  should  be  changed  during  the  system's 
life  cycle,  only  the  one  corresponding  module  must  be 
changed,  thereby  greatly  simplifying  maintenance. 

To  achieve  this,  a designer  must  specify  the  inter- 
face of  the  module  completely  enough  that  any  other 
module  or  any  user  program  can  call  the  module  and  know 
precisely  what  the  module  will  do.  However,  the  inter- 
face must  be  specified  in  such  a way  that  other  modules 
or  programs  do  not  depend  whatsoever  on  how  the  module 
performs  the  task  requested.  SPECIAL  is  a language 
designed  specifically  for  these  goals.  To  implement 
such  a module,  one  writes  a set  of  closely  related 


programs  and  data  structures  conforming  to  the  interface 
specified  . 

One  can  view  such  a module  as  an  abstract  machine, 
abstract  in  the  sense  that  its  implementation  is  unknown 
to  other  modules,  and  abstract  in  the  sense  that  it  is 
most  probably  implemented  in  software  rather  than 
hardware.  SPECIAL  is  based  on  the  analogy  of  an 
abstract  machine.  A real  machine,  such  as  a particular 
computer,  is  always  in  some  state,  represented  by  the 
contents  of  the  CPU  registers  and  the  contents  of  main 
memory.  Similarly,  a module  or  abstract  machine  is 
always  in  some  state,  represented  by  a group  of  values. 
One  can  have  any  portion  of  a computer's  state  printed, 
for  instance,  output  of  the  value  of  any  main  memory 
location,  of  a qeneral  register,  or  of  the  program 
counter.  By  the  same  token,  SPECIAL  lets  a designer 
specify  functions  called  VFUNs  which  output  or  return 
the  value  of  any  of  the  group  of  values  forminq  its 
present  state.  A computer  also  has  operations  which, 
given  the  current  state,  change  the  state;  for  instance, 
an  ADD  instruction  on  the  PDP-11  takes  the  sum  of  the 
contents  of  two  memory  locations  and  stores  it  back  in 
one  of  the  memory  locations,  thereby  changing  the  state 
of  the  machine.  In  the  same  way,  a SPECIAL  module  has  a 
number  of  operations  (called  OFUNs)  at  its  interface 
which  change  the  state  of  the  abstract  machine  or 
module,  given  its  current  state,  by  changinq  some  of  the 
values  comprising  to  current  state. 
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The  heart  of  a module  specification  in  SPECIAL, 
therefore,  is  a list  of  functions  available  at  the  in- 
terface. There  are  several  other  parts  to  a specifica- 
tion, which  are  not  as  central  as  the  list  of  functions. 

Each  specification  describes  some  module  of  a 
software  system.  SPECIAL'S  reserved  words  (such  as 
MODULE,  TYPES,  DEFINITIONS  and  IS)  are  denoted  here  by 
capital  letters.  A module  is  preceded  and  followed  by 
the  words  MODULE  and  END_MODULE . The  name  of  the  par- 
ticular module  immediately  follows  the  word  MODULE.  The 
remainder  of  the  specification  is  hroken  up  into  para- 
graphs or  sections,  each  beginning  with  a reserved  word 
such  as  TYPES,  DECLARATIONS,  PARAMETERS,  DEFINITIONS  and 
FUNCTIONS.  The  paragraphs  are  optional.  Therefore,  the 
structure  of  a module  is  as  follows: 

MODULE  <modul e_name>  „ 

TYPES 

0 

DECLARATIONS 

0 

PARAMETERS 

DEFINITIONS 

0 

FUNCTIONS 

END_MODULE 

Comments  may  appear  throughout  each  module.  A 


■a 
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comment  is  preceded  by  a "$M  and  is  delineated  by  match- 
ing left  and  right  parentheses.  Comments  have  no  effect 
on  the  meaning  of  the  spec i f icat ion  but  only  serve  as  an 
aid  to  understanding. 

The  best  way  to  read  a module  is  to  study  the 
PARAMETERS  section  first  followed  by  the  FUNCTIONS. 
DEFINITIONS,  TYPES  and  DECLARATIONS  paragraphs  should  be 
referenced  as  needed.  Comments  at  the  beginning  of  a 
specification  will  suggest  an  alternative  plan  when  it 
seems  appropriate. 

The  specification  lanquage  defines  objects  and 
operations  on  them.  Associated  with  each  object  is  a 
name  and  a type.  The  type  of  an  object  defines  a set  of 
legal  values  that  the  object  may  have. 

Pr im i tive  types  are  disjoint  sets  of  primitive 
values  which  may  be  either  predefined  or  desig nato rsy 
Predefined  types  include  BOOLEAN,  INTEGER,  REAL  and  CHAR 
(character) . A d esig nato r type  is  a class  of  names  for 
user-defined  objects.  This  new  class  of  objects  is 
defined  by  a particular  module  and  can  only  be  created 
or  modified  using  functions  in  that  module. 

New  types  can  be  formed  by  applying  type- 
constructors  to  the  pr imitive  types.  The  type- 
constructor  VECT0R_0F  creates  a type  which  is  a vector 
(or  randomly  accessible  sequence)  of  objects  for  a qiven 
type.  For  example,  the  type  VECTOR_OF  CHAR  is  the  set 
of  all  possible  sequences  of  characters.  Another  type- 
constructor  is  STRUCT  OF,  which  defines  a record. 


STRUCT_OF  (INTEGER  namel;  CHAR  name2)  defines  records 
consisting  of  two  fields;  the  first  contains  an  integer 
and  may  be  accessed  by  the  name  namel.  The  second  field 
contains  a character  and  may  be  accessed  by  using  name2. 
SET_OF  creates  a type  which  is  a set  of  objects  of  a 
given  type. 

The  purposes  of  the  TYPES  paragraph  are  explained 
with  the  following  example. 

TYPES 

graphs;  DESIGNATOR; 

sequence:  VECTOR_OF  INTEGER; 

As  a result  of  this  TYPES  paragraph,  a new  pr imitive 
data  type  known  as  "nraphs"  is  introduced.  Since  it  is 
a DESIGNATOR,  its  values  come  from  a unique  set  of 
names.  In  additicn,  the  name  "sequence"  is  associated 
with  the  type  specification  VECTOR_OF  INTEGER.  - 

The  objects  defined  by  the  specification  language 
have  a scope  as  well  as  a name  and  a type.  Once  an 
object  has  a name  and  a type  associated  with  it,  the 
scope  dictates  which  parts  of  the  module  may  reference 
that  name.  The  DECLARATIONS  paragraph  is  one  way  to 
associate  a name  with  a data  type.  Furthermore,  the 
scope  of  that  name  will  be  global,  i.e.  its  type  will  be 
the  same  throughout  the  entire  module. 

DECLARATIONS 

graphs  digraph,  cyclic; 

INTEGER  i ; 

"Digraph"  and  "cyclic"  are  both  objects  of  type  "graphs" 
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and  "i"  is  now  declared  as  an  INTEGER. 

The  PARAMETERS  paraqraph  Is  used  to  give  an  object 
a value  when  the  module  is  initialized.  The  value  is  a 
constant  which  would  receive  a particular  value  only 
after  implementation  of  the  module,  when  object  code  is 

v- 

generated.  Parameters  are  global  and  can  therefore  be 
referenced  throughout  the  module. 

PARAMETERS 

INTEGER  max  number_of_  graphs ; 

$(The  maximum  allowable  number  of  "graphs") 

"Max_number_of_graphs"  can  be  used  throughout  the  module 
to  ensure  that  the  total  number  of  "graphs"  never 
exceeds  that  value. 

The  DEFINITIONS  paragraph  is  purely  for  the  con- 
venience of  the  designer  and  reader.  It  is  a macro 
facility.  The  named  object,  when  it  is  used  in  the 
specification,  is  replaced  by  the  particular  expression 
which  it  represents.  For  example, 

DEFINITIONS 

REAL  square_root  (REAL  x;  REAL  toller) 

IS  $(Returns  the  square  root  of  a number,  x,  within  a 
given  tollerance  toller.) 

IF  x<0  OR  toller<=0 
THEN  ? 

ELSE  SOME  REAL  r I 

r*  r-tollerOx  AND 
r*r+toller>=x; 

The  name  of  this  particular  definition  is 
" square_root."  The  value  defined  by  it  has  type  REAL. 

The  list  following  the  name  contains  the  formal  argu- 
ments. Each  time  "square  root"  is  used  it  must  be 


—a mm  mm 


-63- 


immediately  followed  by  a list  of  actual  arguments  that 
agree  in  number  and  type.  Using  "square  root"  causes 
the  expression  followinq  the  word  IS  to  be  textually 
substituted  for  "square  root."  "Square  root"  can  be 
referred  throughout  the  entire  module. 

It  is  apparent  that  the  use  of  the  DEFINITIONS 
paragraph  can  extend  beyond  convenience.  It  can  cut 
down  on  errors  when  definitions  are  long  or  used  repeat- 
edly. In  addition,  should  the  definition  of 
" squa  re_root"  be  changed,  it  is  chanqed  in  one  place 
rather  than  in  each  place  it  is  used. 

The  SOME  construct  used  above  will  be  discussed 
later.  For  anyone  familiar  with  a high  level  program- 
ming language,  the  "square  root"  definition  is  readable 
with  practically  no  further  explanation.  The  only  ex- 
ception is  the  symbol  "?",  which  represents  the  unique 
value  "undefined."  "Square  root"  evaluates  to  "unde- 
fined" when  a square  root  of  a negative  number  is  indi- 
cated or  if  the  tollerance  is  less  than  or  equal  to 
zero . 


Objects  "x"  and  "toller"  do  not  have  to  be  declared 
in  the  DECLARATIONS  paragraph.  An  object  may  be  bound 


to  a type  when  it  is  used 


For 


and  " toller"  , the 


scope  is  the  definition  of  " squareroot."  It  is  not 
important  while  reading  a specification  to  know  the 
scope  of  each  object,  just  its  type.  In  the  example  of 
" squa r enroot" , the  binding  of  "x"  to  type  REAL  occurs  in 
the  definition.  If  there  was  no  binding  of  "x"  in 
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"squareroot"  , the  reader  would  have  to  look  elsewhere 
(perhaps  in  the  DECLARATIONS  paraqraph!  in  order  to  dis- 
cover the  type  of  "x". 

SPECIAL  describes  abstract  machines.  In  other 
words  it  presents  the  functional  capabilities  of  a com- 
putation as  opposed  to  the  implementation  details.  The 
last  and  most  important  paraqraph  contains  a description 
of  the  functions  available  at  the  interface  of  the 
module.  It  is  entitled  FUNCTIONS. 

The  state  of  a module  or  abstract  machine  at  any 
given  instant  is  the  value  of  all  objects  defined  by  the 
module's  specification.  This  state  chanqes  when  at 
least  one  of  the  objects  it  manipulates  changes. 
SPECIAL'S  three  types  of  functions  reflect  this  view  of 
a process.  They  are  VFUN,  OFUN  and  OVFUN.  VFUNs  (value 
functions!  return  a value,  but  do  not  change  the  state 
of  the  module.  OFUNs  (operation  functions)  cause  state 
changes,  but  return  no  value.  The  last  cateqory,  OVFUN, 
causes  a state  change  and  returns  a value. 

Picture  a module  at  some  level  in  a hierarchical ly 
designed  system.  The  functions  in  this  paragraph 
describe  the  interface  between  the  module  and  other 
modules  that  may  reference  it.  The  only  communication 
to  this  module  is  accomplished  via  the  functions. 

For  each  function,  one  may  specify  conditions  under 
which  it  is  invalid  to  call  the  function.  These  are 
called  EXCEPTIONS  and  are  analogous  to  exception  condi- 
tions or  instruction  traps  on  computers;  for  instance, 
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the  division  i nstr uc t ion ( s)  on  most  computers  qenerate 
an  exception  condition  on  division  by  zero.  For  the 
OF  UN  functions,  which  are  operations  chanqinq  the  state 
of  a module,  the  new  state  must  be  defined  precisely  in 
terms  of  the  old  state  and  the  arquments  to  the  new 
function;  the  chanqes  in  the  various  components  of  the 
state  of  the  machine  are  qiven  as  EFFECTS.  For  the  VFUN 
functions,  which  represent  components  of  the  state  of 
the  machine,  the  value  must  be  defined  precisely.  Some 
VFUN  functions  represent  components  of  the  state  not 
accessible  to  the  user,  but  necessary  to  define  the 
semantics  of  other  functions;  these  are  termed  HIDDEN. 
(The  example  of  a stack  indicates  the  need  of  HIDDEN 
functions.  Thouqh  only  the  top  element  is  accessible  to 
the  user,  the  complete  state  of  the  module  depends  on 
the  whole  sequence  of  items  stored  in  the  stack.) 

The  followinq  example  describes  the  characteristics 
of  the  different  function  types.  Althouqh  a bit  con- 
trived, it  will  illustrate  the  main  ideas.  The  example 
defines  a sinqle  "reqister."  It  can  be  initialized  to  an 
INTEGER  value,  have  another  INTEGER  value  added  to  it  or 
have  twice  its  value  returned.  Assume  that  in  the 
PARAMETERS  paraqraph,  " max_req i ster_val ue"  has  been 
declared  as  an  INTEGER.  It  is  intended  to  be  the  max- 
imum absolute  value  that  can  be  stored  in  the  "reqis- 
ter." 

FUNCTIONS 

VFUN  req ister ( ) ->  INTEGER  value; 

$(Returns  the  value  stored  in  the  "reqister".) 


-66- 


HIDDEN; 

INITIALLY 

value*?; 

OFUN  load  register  (INTEGER  i); 

$(Stores  T in  the  "register.") 

EXCEPTIONS 

max_reg ister_value< i ; 
maxreg i ster  value<-i; 

EFFECTS  T" 

'register(  )=i; 

OVFUN  add  (INTEGER  i)  ->  INTEGER  value; 

$(Adds  "i"  to  the  contents  of  the  "register"  and  returns 
the  new  value  as  the  value  of  the  function.) 

EXCEPTIONS 

register(  )*?; 

max_reg ister_value< reg ister ( ) + i ; 
max_reg ister_value<- (register ( )+i) ; 

EFFECTS 

value* ’ reg ister ( ); 

'register(  )=register(  )+i; 

VF UN  double  ( ) ->  INTEGER  value; 

$(Returns  double  the  contents  of  the  "register.") 
EXCEPTIONS 

register(  )*?; 

DERIVATION 

register(  )*2; 


The  first  function  is  a VFUN  called  "register," 
which  has  no  formal  arguments.  The  value  returned  by 
this  function  is  an  INTEGER  as  indicated  by  the  informa- 
tion following  the  symbol  "->".  "Value"  has  been  bound 
to  type  INTEGER.  The  scope  of  its  binding  is  the  func- 
tion definition.  Corresponding  to  the  discussion  of  the 
object  " x"  in  the  example  of  " square- root" , "value" 
could  have  been  bound  to  INTEGER  elsewhere. 

After  the  comment  is  the  reserved  word  HIDDEN. 
VFUNs  may  be  hidden  as  the  reserved  word  indicates  or 
visible.  Visible  VFUNs  are  available  at  the  interface 
whereas  hidden  VFUNs  are  not  available  outside  of  the 
module.  Hidden  VFUNs  are  used  by  the  designer  for 
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purposes  of  description. 

The  reserved  word  INITIALLY  indicates  that  this 
VFUN  is  pr im i t iv e . This  means  that  an  initial  value  for 
the  VFUN  exists.  The  initial  value  for  "reqister"  is 
"?"  or  "undefined."  All  of  the  pr im it ive  VFUNs  together 
define  the  state  of  the  module. 

The  next  function,  " load _req i ster " , is  an  OFUN;  it 
therefore  causes  a state  chanqe.  It  takes  a sinqle 
INTEGER  parameter.  As  the  comment  indicates,  the 
parameter's  value  is  to  be  placed  into  the  "reqister." 

The  next  keyword  in  " loadreq ister"  is  EXCEPTIONS. 
An  EXCEPTIONS  section  appears  in  all  except  HIDDEN  func- 
tions. They  describe  conditions  under  which  the  func- 
tion cannot  be  called.  If  any  of  the  statements  (excep- 
tion conditions)  in  the  EXCEPTIONS  section  are  true, 
then  no  state  change  takes  place  and/or  no  value  ie 
returned.  As  was  previously  stated, 
"max_reg i ster_val ue"  is  a parameter  which  represents  the 
maximum  absolute  value  storable  in  "reqister."  The  two 
exception  \cond  itions  prevent  an  integer  which  is  outside 
the  acceptable  range  from  being  placed  into  the  "regis- 
ter." 

If  no  exception  conditions  prevent  the  function 
from  executing,  the  EFFECTS  section  describes  the  state 
change.  In  defininq  a state  change,  we  must  refer  to 
the  new  values  for  components  (VFUNs)  of  the  state  in 
terms  of  old  values.  Placing  the  symbol  quote  before 
the  function  name  "reqister"  is  the  value  in  the  new 
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state , i.e.  the  value  returned  by  a call  to  "register" 
after  the  call  to  " load_reg ister ."  Therefore,  the  effect 
of  this  OFUN  is  that  a subsequent  call  to  "register" 
will  return  the  value  "i".  Note,  the  new  state  of  the 
process  is  completely  represented  by  the  values  returned 
by  all  pr  im i t ive  VFUNs. 

The  next  function  is  an  example  of  an  OVFUN  func- 
tion. "Accumulate"  takes  one  argument,  an  INTEGER,  and 
returns  an  INTEGER  value.  The  comments  indicate  the 
effects  this  function  has  on  the  state  as  well  as  the 
value  returned.  Since  this  function  is  visible,  there 
is  an  EXCEPTIONS  section.  "Accumulate"  cannot  effect 
the  state  of  the  process  if  the  contents  of  "register" 
is  "undefined."  This  is  controlled  by  the  first  excep- 
tion condition.  The  second  and  third  exception  condi- 
tions restrict  the  new  value  in  "reqister"  to  he  withifr 
the  acceptable  range.  Exception  conditions  have  an  ord- 
ering: the  first  is  checked,  then  the  second  and  so  on. 
This  is  unlike  the  EFFECTS  section  where  all  changes 
occur  simultaneously.  As  a result  of  a call  to  "accumu- 
late," the  new  value  returned  by  "register"  is  equal  to 
the  value  returned  by  "register"  before  this  function 
call  plus  "i."  Lastly,  the  value  returned  is  the  value 
that  will  be  returned  by  the  function  "register"  after 
the  call  to  "accumulate." 

"Double_register"  is  the  last  function.  It  is  a 
VFUN  which  has  an  empty  argument  list  and  returns  an 
INTEGER  value.  The  only  exception  condition  is  that  the 


function  " double_req ister"  is  d er ived  (as  indicated  by 
the  keyword  DERIVATION).  Its  value  is  defined  or 
derived  in  terms  of  other  VFUNs.  The  value  returned  by 
"double_req ister"  is  the  current  value  of  "reqister" 
times  two. 

In  conclusion,  the  three  types  of  functions  are 
VFUNs  (value  functions),  OFUNs  (operation  functions)  and 
OVFUNs  (operation  and  value  functions).  Each  VFUN  is 
either  hidden  or  visible,  dependinq  on  whether  it  is 
available  outside  of  the  module.  The  value  returned 
from  a VFUN  is  derived  or  pr  im  itive.  OFUNs  and  OVFUNs, 
like  visible  VFUNs,  have  EXCEPTIONS  or  conditions  under 
which  they  will  not  be  executed.  Should  no  exception 
condition  arise,  the  effects  of  an  OFUN  or  OVFUN  ar* 
described  in  the  EFFECTS  section. 

A few  more  lanquaqe  details  must  be  explained.  The 
majority  of  SPECIAL'S  constructs  are  intuitively 
equivalent  to  hiqh  level  lanquaqe  expressions  (i.e.  IF- 
THEN-ELSE).  The  remaininq  expressions  that  are  particu- 
lar to  the  specification  lanquaqe  and  that  appear  in  the 
enclosed  examples  will  now  be  described. 

As  previously  mentioned,  type-constructors  are  used 
to  build  new  types  from  pr imitive  ones.  Three  type- 
constructors  are:  VECTOROF,  SETOF  and  STRUCT_OF. 

Vectors  are  defined  explicitly, 

VECTOR (2  4 6) 
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or  implicitly, 

VECTOR (FOR  j FROM  1 TO  3:  2*j) . 

These  two  expressions  define  the  same  sequence  of  three 
numbers.  Note  that  the  object  "j"  in  the  implicit  vec- 
tor need  not  be  declared  as  INTEGER;  this  is  assumed. 
If  A is  a vector,  then  LENGTH (A)  returns  the  number  of 
elements  in  A.  The  third  element  in  A may  be  referenced 
by  A [3]. 

Sets  may  be  defined  implicitly  such  as  the  follow- 
ing expression: 

{INTEGER  i I i>3  AND  i < = 7 } . 

This  set  contains  elements  4,  5,  6 and  7.  The  symbol 
"I"  is  read  as  "such  that."  The  entire  expression  is 
read  "the  set  of  INTEGER  i such  that  i is  greater  than  Z 
and  i is  less  than  or  equal  to  7."  CARDINALITY  returns 
the  number  of  elements  in  the  set  which  is  its  operand. 

The  SOME  expression  returns  any  value  having  a 
given  property  (or  equivalently,  satisfying  a given 
predicate.  For  example, 

SOME  x I T (x) 

translates  as  "some  x such  that  T(x)  is  true." 

Assume  a new  type  called  "record"  is  defined  by  the 
statement : 

record:  STRUCT  OF (INTEGER  identification;  INTEGER 


value) 
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If  the  object  A is  of  type  "record,"  then  the  expression 
A. value  references  the  second  item  in  the  structure. 
A=STRUCT (1 ; 3)  assigns  "A"  the  value  of  a structure  where 
A. identi f ication  equals  1 and  A. value  equals  3. 

A DESIGNATOR  is  used  to  define  a set  of  names  to 
reference  elements  of  a new  class  of  objects.  The  func- 
tion NEW  applies  to  designators  only.  NEW(t)  generates 
a name  that  has  never  been  used  before.  " t"  must  have 
been  defined  as  a designator  in  the  TYPES  paragraph  by 
the  expression  t:  DESIGNATOR. 

The  LET  expression  provides  a local  definition  of  a 
value.  The  scope  of  the  definition  is  the  expression 

LET  INTEGER  j = 

CARDINALITY ({INTEGER  k I 
k">0  AND 
k<50}) 

IN 

<express ion> 

The  object  "j"  is  defined  and  bound  for  the  duration  of 
the  expression  following  the  keyword  IN.  (Of  course, 
the  value  of  j in  the  example  happens  to  be  49.) 

Lastly,  SPECIAL  has  an  expression  for  universal 
quanti f ication. 

FORALL  x I T (x)  : U(x) 


is  read  "forall  x such  that  T(x)  is  true,  Q(x)  is  true." 
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Appendix  II 
Stacks 


A.  Keywords:  stack,  pushdown,  LIFO,  LIFO  queue 


B.  References 

The  concept  of  a stack  is  defined  in  many  texts.  One  is 
chapter  three  of  Fundamentals  of  Data  Structures,  by  Ellis 


Horowitz  and  Sartaj  Sahni,  Computer  Science  Press,  Inc.,  1976. 
For  ideas  on  implementing  the  module,  chapters  three  and  four  of 
the  same  text  present  several  strategies. 


C.  Hidden  Information 

This  module  hides  all  decisions  about  implementing  a 
stack.  For  instance,  users  of  the  module  cannot  answer  the 
following  questions:  Are  the  stacks  implemented  using  an  array  or 
linked  list?  Do  all  stacks  share  one  array  or  does  each  have  its 
own  array?  How  many  words,  bytes,  or  bits  are  used  per  data 
element  in  the  stack? 


D.  Description  (an  aid  to  understanding  the  definition,  though 
the  definition  is  the  arbitrator  of  all  issues  or  questions 
raised) 


This  module  manages  any  number  of  stacks  up  to  the 
implementation  constant  "maxstacks."  The  data  structure 
represented  by  a stack  maintains  a sequence  of  items.  One  can 
add  an  item  to  the  sequence  using  "push",  which  adds  the  item  at 
one  fixed  end  of  the  sequence.  An  item  may  be  removed  from  the 
sequence  at  that  same  fixed  end  using  "pop",  which  besides 
removing  the  item,  gives  its  value  as  the  value  of  the  procedure 
call.  One  may  obtain  that  value  without  removing  the  data  item 
from  the  sequence  via  "top."  The  only  other  operation  is  to  ask 
whether  there  are  any  elements  in  the  sequence  or  not,  via 
"empty."  The  maximum  length  of  any  sequence  is  "maxsize."  For 
this  specification,  the  data  items  are  integers  whose  absolute 
value  is  bounded  by  "maxelement . " New  stacks  may  be  created  and 
old  stacks  released  via  "create_stack"  and  "delete_stack . " 

Note  particularly  that  the  function  "stack(s)"  is  HIDDEN. 
Therefore,  it  can  never  be  called,  nor  does  it  imply  an 
implementation  using  arrays  or  sequential  memory.  It  merely 
indicates  the  effects  of  "push"  and  "pop"  on  the  sequence  of 
items.  The  specification  implies  that  only  the  element  most 
recently  entered  into  the  data  structure  may  be  accessed  or 


removed ; 
or  LIFO. 


this  property  has  led  to  the  phrase  "last-in-first-out 


E.  Modifications 

Stacks  of  course  do  not  have  to  be  sequences  of  integers. 
The  declarations  which  must  be  changed  for  REALS,  CHARs,  or 
whatever  is  desired  are  marked  by  comments  in  the  specf ication . 

For  certain  applications,  one  may  wish  to  access  any 
element  in  the  sequence,  but  add  or  delete  items  at  only  one 
fixed  end.  For  this,  one  may  add  another  function: 


VFUN  val ue ( s ; INTEGER  j)->i; 

$ (random  access  read  of  data 
items  in  stack) 

EXCEPTIONS 
stack (s) »? ; 
j<l  OR  j>size (s)  ; 

DERIVATION 
stack (s) [ j] ; 

$(Note  that  value  (s;l)  is  the 
first  element  added  to  the 
sequence,  not  the  last  one.) 


Another  function  one  may  wish  to  add  to  the  interface  is 
the  number  of  elements  in  a stack.  "Size"  in  the  DEFINITIONS 
section  suggests  how  to  add  that  feature. 


F.  Alternatives 

In  some  applications  such  as  implementations  of 
programming  languages,  a pointer  into  the  stack  may  be  desirable. 
The  pointer  may  be  used  as  a local  reference  point  for 
selectively  reading  values  stored  in  the  stack  or  removing  many 
items  simultaneously.  Refer  to  the  specification  stackl  for  such 
a feature. 
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MODULE  stacks 


TYPES 

stack  name:  DESIGNATOR; 


DECLARATIONS 

INTEGER  i;  $(  This  is  for  a stack  of  integers.  The  declarations 

must  be  changed  for  a different  type  of  data  element.) 

stack  name  s; 


PARAMETERS 

INTEGER  max_stack_s i ze  $(  maximum  size  of  any  stack)  , 

max_number_of_stacks  $(  maximum  number  of  stacks  permitted), 
max_element_value  $(  maximum  absolute  value  storable  in 

any  stack) 

$(  For  a stack  of  a different  data  type 
than  INTEGER,  this  definition  must  be 
changed . ) ; 


DEFINITIONS 

INTEGER  number_of_stacks 

IS  CARDINALITY ( { stack_name  s | stack (s)  ~=  ? }); 
INTEGER  size  of  stack (s)  IS  LENGTH (stack (s)  ) ; 


FUNCTIONS 


VFUN  stack (s)  ->  VECTOR_OF  INTEGER  v; 

$(  Represents  contents  of  stack  s.  This  declaration  of 
INTEGER  must  be  changed  for  a different  type  of  data 
element . ) 

HIDDEN; 

INITIALLY 
v = ?; 

VFUN  empty(s)  ->  BOOLEAN  b;  $(  This  function  returns  true,  if 

stack  s is  empty,  otherwise  false.) 

EXCEPTIONS 

stack(s)  ■ ?; 

DERIVATION 

size  of  stack(s)  * 0; 
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VFUN  to-'  ><*)  ->  i;  $(  Returns  the  value  most  recently  pushed  onto 

stack  s.) 

EXCEPTIONS 

stack(s)  = ?; 
empty (s) ; 

DERIVATION 

stack (s)  [s ize_of_stack (s)  ] ; 

$(  One  might  add  another  derived  VFUN  which  is  just  the 
macro  size(s)  so  that  the  number  of  elements  in 
the  stack  is  accessable.) 

0 VFUN  create__stack  ( ) ->  s;  $(  Initializes  a new  stack.) 

EXCEPTIONS 

number_of_stacks  >=  max_number_of  stacks; 

EFFECTS 

S * NEW (stack_name) ; 

'stack  (s)  = VECTORO  ; 

OFUN  delete_stack ( s ) ; $(  Delete  makes  stack  s and  its  contents 

unavailable . ) 

EXCEPTIONS 

stack(s)  = ?; 

EFFECTS 

'stack(s)  = ?; 

OFUN  push (s ; i) ; 

$(  Push  adds  i to  the  stack  s,  thereby  guaranteeing  that 
s is  not  empty,  and  making  i the  element  returned  by  top 
(s).) 

EXCEPTIONS 

stack(s)  = ?; 

size_of_stack (s)  >=  max_stack_size ; 

i <(0  - max_element_value)  OR  i > max  element  value; 

EFFECTS 

' stack  (s) 

» VECTOR (FOR  j FROM  1 TO  size_of_stack (s)  + 1 
; IF  j O size_of  stack  (s) 

THEN  stack (s) [J] 

ELSE  i ) ; 

OVFUN  pop(s)  ->  i;  $(  Removes  item  last  pushed  onto  stack  s.) 
EXCEPTIONS 

stack(s)  = ?; 
empty (s)  ; 

EFFECTS 

i * top (s)  ; 

'stack (s) 

= VECTOR (FOR  j FROM  1 TO  s ize_of_stack (s)  - 1 
: stack  (s)  ( j] ) ; 


END  MODULE 
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Appendix  III 
Queues 


A.  Keywords:  queue,  FIFO 


B.  References 

The  concept  of  a queue  is  defined  in  many  texts.  One  is 
chapter  three  of  Fundamentals  of  Data  Structures,  by  Ellis 


Horowitz  and  Sartaj  Sahni,  Computer  Science  Press,  Inc.,  1S76. 
Chapters  three  and  four  of  the  same  text  present  several 
str ateg ies . 


C.  Hidden  Information 

This  module  hides  all  decisions  about  how  the  queue  is 
represented  in  memory.  For  instance,  one  does  not  know  whether 
an  array  is  used,  a linked  list,  or  some  other  structure  in 
memory.  Perhaps  each  queue  has  its  own  memory  space,  or  perhaps 
they  share  a common  memory  pool.  Whether  more  than  one  queue 
element  is  packed  per  word  is  also  hidden.  Even  though  the 
specification  appears  to  imply  that  the  newest  element  of  the 
queue  enters  at  the  left  end,  this  is  not  necessarily  true. 


D.  Description  (an  aid  to  understanding  the  definition,  though 
the  definition  is  the  arbitrator  of  all  issues  or  questions 
raised) 


The  module  manages  any  number  of  queues  up  to 
"max_number_of_queues . " A queue  is  a sequence  of  data  items  very 
much  like  a line  of  individuals  at  a bank  teller's  window.  Items 
enter  the  sequence  only  at  the  back  end  of  a queue;  "enqueue"  is 
the  operation  to  add  a data  value  to  the  queue.  The  first  value 
placed  in  the  queue  is  the  first  to  be  removed;  the  last  entered 
is  the  last  to  be  removed.  (This  has  led  to  its  name  as 
"first-in-first-out"  or  FIFO.)  "Dequeue"  removes  one  item  from 
the  queue,  similar  to  the  person  at  the  front  of  a line  being  the 
first  to  leave.  "Dequeue"  returns  as  a value  that  data  item 
which  is  removed.  To  merely  read  the  value  which  would  be 
removed  by  the  next  use  of  "dequeue",  the  function  "front"  is 
provided;  the  value  remains  in  the  queue,  changing  nothing. 

Only  one  item  may  be  examined  in  the  queue  at  any  time. 
Also,  the  relative  order  of  the  elements  with  respect  to  one 
mother  cannot  be  changed  and  is  determined  solely  by  the  order 
- which  they  were  enqueued. 


I 

I 


To  find  out  whether  the  queue  has  any  elements  in  it, 
"empty"  is  used;  it  does  not  change  the  queue  at  all.  If  you 
want  a new  queue,  "create_queue"  provides  as  a value  the  name  of 
a new  queue.  To  release  a queue  named  q,  "abol ish_queue"  is 
used . 


The  maximum  sequence  length  is  "max_queue_size . " In  this 
specification,  all  values  in  the  queue  are  integers  whose 
absolute  value  is  bounded  by  "max_element_value . " 

Especially  note  that  function  "queue(q)"  is  HIDDEN.  Thus, 
one  can  never  refer  to  such  a function;  it  is  not  part  of  the 
interface.  Though,  the  specification  may  seem  to  suggest  an 
implementation  using  an  array,  following  that  thought  would  lead 
to  a very  inefficient  implementation,  causing  a shift  of  every 
queue  element  with  each  "enqueue."  In  fact,  all  that  is  implied 
by  the  specfication  is  that  the  relative  order  of  the  queue 
elements  is  exactly  the  order  in  which  elements  were  enqueued  and 
that  only  the  item  available  through  "front"  or  "dequeue”  may  be 
read . 


E.  Modifications 

If  data  values  other  than  integers  are  desired,  several 
declarations,  which  are  commented  in  the  specification,  must  be 
changed.  If  a count  of  the  number  of  elements  in  a .queue  is 
desired,  "size"  should  be  made  a VFUN  rather  than  its  present 
status  as  a DEFINITION. 


F.  Alternatives 

For  certain  applications,  we  may  wish  to  assign  some 
importance,  weight,  or  priority  to  the  elements,  and  order  them 
based  on  that  first,  then  on  order  of  entry.  See  the 
specification  of  pr ior ity_queues  for  such  a data  structure. 
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MODULE  queues 


TYPES 

queue_name:  DESIGNATOR; 


DECLARATIONS 

INTEGER  i;  $(  This  is  for  a queue  of  integers.  This  declaration 

must  be  changed  for  a different  type  of  data  element.) 
queue_name  q;  < 


PARAMETERS 

INTEGER  max_queue_size  $(  maximum  size  of  any  queue)  , 

max_number_of_queues  $(  maximum  number  of  queues)  , 
max__element_value 

$(  The  maximum  absolute  value  storable  in  any  queue.  For 
a queue  of  a different  type  other  than  INTEGER,  this 
definition  must  be  changed.); 


DEFINITIONS 

INTEGER  number_of_queues 

IS  CARDINALITY ( { queue_name  q | queue (q)  ~=  ? }); 
INTEGER  size(q)  IS  LENGTH (queue (q) ) ; 


FUNCTIONS 


VFUN  queue (q)  ->  VECTOR_OF  INTEGER  s; 

$(  This  declaration  of  INTEGER  must  be  changed  for  a 
different  type  of  data  element.  This  is  the  sequence 
of  elements  added  to  q.  The  most  recently  added 
is  at  queue (q)[l].  The  oldest  entry  is  the  last 
element  in  the  sequence.) 

HIDDEN; 

INITIALLY 

O f f 

VFUN  empty (q)  ->  BOOLEAN  b;  $(  Value  is  true  if  queue  q is  empty, 

otherwise  false.) 

EXCEPTIONS 

queue (q)  = ?; 


DERIVATION 

size(q)  = 0; 
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VFUN  front (q)  ->  i;  $(  Returns  value  least  recently  enqueued  or  added 

onto  queue  q,  and  which  has  also  not  been 
subsequently  dequeued.) 

EXCEPTIONS 

queue(q)  * ?; 
empty (q) ; 

DERIVATION 

queue  (q)  [size (q) ] ; 

$(  One  might  add  another  derived  VFUN  which  is  just  the 
macro  size(q)  so  that  the  number  of  elements  in 
any  queue  can  be  accessed  outside  of  the  module.) 

OVFUN  create_queue ( ) ->  q;  $(  Initiates  a new  queue,  returning  the 

name  of  that  queue  as  the  function's 
value . ) 

EXCEPTIONS 

number_of_queues  >=  max _number_of_queues ; 

EFFECTS 

q = NEW (queue_name) ; 

'queue (q)  * VECTOR () ; 

OFUN  abol ish_queue (q) ; $(  Makes  queue  q and  any  contents 

unaccessable . ) 

EXCEPTIONS 

queue (q)  * ?; 

EFFECTS 

'queue (q)  * ?; 

OFUN  enqueue (q;  i); 

$(  Enqueue  adds  i to  the  queue  q,  thereby  guaranteeing 
that  q is  not  empty,  i would  be  returned  by  front  only 
after  preceding  enqueued  values  have  been  removed 
using  dequeue.) 

EXCEPTIONS 

queue (q)  ■ ?; 

size(q)  >•  max_queue_size ; 

i <(0  - max_element_value)  OR  i > max_element_value ; 

EFFECTS 

'queue (q) 

* VECTOR (FOR  j FROM  1 TO  size (q)  +1 

: IF  j > 1 THEN  queue(q)[j  - 1]  ELSE  i) ; 


OVFUN  dequeue (q)  ->  i 


EXCEPTIONS 

queue (q)  * ?; 
empty (q) ; 

EFFECTS 

i * front (q)  ; 

'queue (q) 

- VECTOR (FOR  j FROM  1 TO  size(q) 


$(  Removes  item  least  recently  added  by 
enqueue  onto  queue  q.) 


1:  queue (q) [ j] ) ; 


END  MODULE 


Appendix  IV 
Trees 


A.  Keywords:  tree,  binary  tree,  hierarchy,  hierarchical  data 

structure 


B.  References 

The  concept  of  a tree  is  defined  in  many  texts.  One  is 
chapter  five  of  Fundamentals  of  Data  Structures,  by  Ellis 


Horowitz  and  Sartaj  Sahni,  Computer  Science  Press,  Inc.,  1976. 


C.  Hidden  Information 

This  module  hides  all  decisions  about  how  the  tree  is 
represented  in  memory.  For  instance,  one  does  not  know  whether 
an  array  is  used,  a linked  list,  or  some  other  structure. 
Perhaps  each  tree  has  its  own  memory  space,  or  perhaps  they  share 
a common  memory  pool.  Whether  more  than  one  tree  element  is 
packed  per  word  as  well  as  the  specific  algorithms  for  performing 
inorder,  preorder  and  postorder  traversals  are  also  hidden. 


D.  Description  (an  aid  to  understanding  the  definition,  though 
the  definition  is  the  arbitrator  of  all  issues  or  questions 
raised) 


This  module  manages  any  number  of  binary  trees  up  to 
"max_number_of_trees . " A binary  tree  is  a finite  set  of  zero  or 
more  nodes.  A non-empty  binary  tree  has  a special  node  known  as 
the  root.  Up  to  two  nodes  can  be  directly  associated  with  a 
node.  They  are  called  the  leftson  and  the  rightson  of  that  node. 
This  node  is  then  designated  as  the  father  and  no  other  node  may 
be  the  father  of  either  the  leftson  or  rightson.  Nodes  can  have 
a unit  of  information  associated  with  them.  In  this  module  the 
information  is  an  integer  that  has  a maximum  absolute  value  of 
"max_value."  Finally,  the  maximum  number  of  nodes  on  any  binary 
tree  is  "max_number_of_nodes  . " 

A tree  or  its  contents  cannot  be  accessed  directly  at  the 
interface.  Two  HIDDEN  functions  are  provided  in  order  to 
describe  the  contents  of  a tree  and  to  reflect  the  changes  which 
occur  to  it.  They  are  "tree"  and  "node." 

The  function  "create_tree"  initiates  a new  tree.  At  this 
point  the  new  tree  contains  no  nodes.  " In itial ize_root"  adds  a 
root  node  to  an  empty  tree.  A leftson  or  rightson  may  be 
associated  with  an  existing  node  via  the  functions 


-81- 


"initialize  left  son”  and  "initialize  right  son." 


Each  node  of  a 
associated  with  it.  The 
and  "right_son"  return 
that  relationship  to 


"value_of_node"  store 
"Ex  ists_lef t_son"  and 
return  true  if  a node 
To  delete  a node  the 


particular  tree  has  an  identification 
functions  "father  of_node",  "left_son", 
the  identification  for  the  node  having 
the  given  one.  "Set  value"  and 


and  retrieve  node  values  Tn  the  tree, 
"exists  right_son"  are  predicates  which 
has  a leftson  or  rightson,  respectively, 
function  "delete  node"  should  be  used. 


"Delete_tree"  will  delete  an  entire  tree  thereby  making  it  and 
its  nodes  unavailable.  Lastly,  three  functions  are  provided  for 
tree  traversals.  The  tree  traversals  visit  each  node  in  the  tree 
exactly  once,  returning  the  node  identifiers  for  each  node  in  the 
order  visited.  The  three  orders  are  preorder,  inorder  and 
postorder  which  correspond  to  prefix,  infix  and  postfix  forms  of 
an  expression.  The  functions  are  "preorder_tr aver sal " , 
"inorder  traversal"  and  "postorder  traversal." 


E.  Modifications 

Trees,  of  course,  do  not  have  to  contain  integers  as 
values  of  the  nodes.  The  appropriate  declarations  would  have  to 
be  changed. 


F.  Alternatives 


general 


In  some  applications, 
n_ary  tree,  as  opposed 


such  as  certain  sorts,  the  more 
to  the  binary  tree,  is  desirable. 
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MODULE  trees 

$(  It  is  probably  best  to  study  the  specification  in  the 
following  order:  node  structure  under  TYPES  first; 
create_tree  and  initial ize_root  for  creating  a new  tree? 
initial ize_left_son  or  lnitialize_r ight_son  to  set  up 
children;  f ather_of_node , left_son,  and  right_son  to 
find  a node  having  that  relationship  to  the  given  one? 
set_value  and  value_of_node  to  store  and  retrieve  values 
in  the  tree;  and  the  remaining  features.) 


TYPES 

tree_name:  DESIGNATOR? 

node_structure : 

STRUCT_OF( INTEGER  father; 

INTEGER  value; 

INTEGER  leftson; 

INTEGER  rightson); 

$<  For  a tree  holding  a different  data  type  other  than 
INTEGER,  the  declaration  for  value  must  be  changed.) 

$(  A node  has  four  pieces  of  information  potentially: 
the  identity  of  the  father,  the  value  stored  at  the  node, 
the  identity  of  a leftson,  and  the  identity  of  a rightson. 
This  fact  is  indicated  by  our  use  of  the  STRUCTure 
construct;  the  specification  refers  to  any  of  the*  four 
pieces  of  information  in  a structure  s by  writing  s. father 
for  the  father  information,  s. value  for  the  value,  etc.) 


DECLARATIONS 

INTEGER  id,  i,  j; 
tree_name  t? 
node  structure  n; 


PARAMETERS 

INTEGER  max_number_of_trees , $(  maximum  allowable  number  of  trees) 
max_number_of_nodes , $(  maximum  allowable  number  of  nodes 

on  a tree) 

max_value 

$(  The  maximum  absolute  value  storable  in  any  node.  For  a 
data  type  other  than  INTEGER,  this  declaration  must  be 
changed . ) ? 
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DEFINITIONS 

SET_OF  INTEGER  nodes_in_tr ee ( t ) 

IS  { INTEGER  id  I node(t,  id)  ~=  ? }; 

INTEGER  size_of_tree (t)  IS  CARDINALITY  (nodes__in_tree  ( t ))  ; 

INTEGER  number_of_trees 

IS  CARDINALITY ({  tree_name  t | tree(t)  ~=  ? }); 

VECTOR_OF  INTEGER  combine_vectors ( VECTOR_OF  INTEGER  vl; 

VECTOR__OF  INTEGER  v2; 

VECTOR_OF  INTEGER  v3) 

IS  $(  A vector  which  is  the  concatenation  of  vectors 
vl,  v2  and  v3.) 

VECTOR (FOR  j 

FROM  1 

TO  LENGTH (vl)  + LENGTH (v2)  + LENGTH (v3) 

: IF  j <=  LENGTH (vl) 

THEN  vl[j] 

ELSE  IF  j <=  LENGTH (vl)  + LENGTH (v2) 

THEN  v2 [ j - LENGTH (vl)] 

ELSE  v3 [ j - (LENGTH (vl)  + LENGTH (v2) )]) ; 
VECTOR_OF  INTEGER  preorder (t;  id) 

IS  $(  A vector  of  integers,  which  represents  all  node 

identifiers  for  the  tree  t,  in  a preorder  traversal,  id  is 
the  identifier  of  the  root  node  of  the  tree.) 

IF  id  * ? 

THEN  VECTOR () 

ELSE  combine_vectors (VECTOR ( id) , .. 

preorder (t,  node(t,  id) .leftson) , 
preorder (t,  node(t,  id ) . r ightson) ) ; 
VECTOR_OF  INTEGER  inorder (t;  id) 

IS  $(  A vector  of  integers,  which  represents  all  node 

identifiers  for  the  tree  t,  in  an  inorder  traversal,  id  is 
the  identifier  of  the  root  node  of  the  tree.) 

IF  id  = ? 

THEN  VECTOR () 

ELSE  corabine_vectors ( inorder (t , node(t,  id) .leftson)  , 

VECTOR (id) , 

inorder  (t,  node(t,  id) .r ightson) ) ; 
VECTOR_OF  INTEGER  postorder (t;  id) 

IS  $(  A vector  of  integers,  which  represents  all  node 

identifiers  for  the  tree  t,  in  a postorder  traversal,  id  is 
the  identifier  of  the  root  node  of  the  tree.) 

IF  id  = ? 

THEN  VECTOR () 

ELSE  combine_vectors (postorder (t , node(t,  id) . leftson)  , 

postorder (t,  node(t,  id) .r ightson)  , 
VECTOR (id) ) ; 

INTEGER  root_id(t) 

IS  $(  The  identifier  of  the  root  node  for  tree  t.) 

SOME  INTEGER  i | father  of  node(t,  i)  » 0; 


- ■ . . .■•Ufc.lw*. 


FUNCTIONS 


VFUN  node(t;  i)  ->  n; 

HIDDEN; 

INITIALLY 

node(t,  i)  = ? 


$(  Returns  the  node  n in  tree  t with 
identifier  i.) 


VFUN  tree(t)  ->  BOOLEAN  b;  $(  Predicate,  which  returns  true  if 

tree  t exists,  otherwise  false.) 

HIDDEN; 

INITIALLY 

FALSE; 

VFUN  father_of_node ( t ; i)  ->  id; 

$(  Returns  the  identifier  for  the  node  which  is  the 
father  of  node  i on  tree  t.  Returns  zero  for  the  root.) 
EXCEPTIONS 

NOT  tree (t)  ; 
node(t,  i)  = ?; 

DERIVATION 

node ( t , i)  .father ; 

VFUN  left_son(t;  i)  ->  id;  $(  Returns  the  identifier  for  the  node 

which  is  the  leftson  of  node  i on 
tree  t.) 

EXCEPTIONS 

NOT  tree  (t)  ; 
node(t,  i)  * ?; 

NOT  exists_lef t_son ( t , i) ; 

DERIVATION 

node(t,  i). leftson; 

VFUN  right_son(t;  i)  ->  id;  $(  Returns  the  identifier  for  the  node 

which  is  the  rightson  of  node  i on 
tree  t.) 

EXCEPTIONS 

NOT  tree  (t)  ; 
node(t,  i)  * ?; 

NOT  exists_right_son(t,  i) ; 

DERIVATION 

node(t,  i)  . rightson; 

VFUN  exists_left_son (t;  i)  ->  BOOLEAN  b; 

$(  Predicate  which  returns  true,  if  node  i on  tree  t has 
a leftson,  otherwise  false.) 

EXCEPTIONS 

NOT  tree (t)  ; 
node(t,  i)  * ?; 

DERIVATION 

node(t,  i). leftson  “■  ?; 
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VFUN  ex ists_r ight_son ( t ; i)  ->  BOOLEAN  b; 

$(  Predicate  which  returns  true,  if  node  i on  tree  t has 
a rightson,  otherwise  false.) 

EXCEPTIONS 

NOT  tree ( t) ; 
node(t,  i)  = ?; 

DERIVATION 

node(t,  i). rightson  ~=  ?; 

VFUN  value_of_node ( t ; i)  ->  j; 

Returns  the  stored  value  of  node  i on  tree  t.  The  type 
of  j must  be  changed  for  a data  type  other  than  INTEGER.) 
EXCEPTIONS 

NOT  tree  (t)  ; 
node(t,  i)  = ?; 
node(t,  i) .value  = ?; 

DERIVATION 

node (t,  i)  .value  ; 

OFUN  delete_node ( t ; i);  $(  Deletes  leaf  node  i on  tree  t.) 

EXCEPTIONS 

NOT  tree  ( t ) ; 
node(t,  i)  = ?; 
exists_left_son (t,  i) ; 
exists_right_son(t,  i)  ; 

EFFECTS 

IF  f ather_of_node  ( t , i ) =0  ** 

THEN  $(  The  node  is  the  root  node.)  'node(t,  i)  = ? 

ELSE  IF  node(t,  f ather_of_node ( t , i )). leftson  = i 

THEN  $(  The  node  is  the  leftson  of  some  node.) 
'node(t,  father_of_node (t,  i)). leftson  ■ ? 

AND  'node(t,  i)  ■ ? 

ELSE  $(  The  node  is  the  rightson  of  some  node.) 
'node(t,  f ather_of_node ( t , i)). rightson  - ? 

AND  'node(t,  i)  = ?; 

OFUN  delete_tree (t) ; $(  Deletes  an  entire  tree.) 

EXCEPTIONS 

NOT  tree  ( t ) ; 

EFFECTS 

' tree  (t)  = FALSE; 

FORALL  i I node(t,  i)  “*»  ?:  'node(t,  i)  = ?; 

OVFUN  create_tree ( ) ->  t;  $(  Initiates  a new  tree,  returning  the 

name  of  that  tree  as  the  function's 
value . ) 

EXCEPTIONS 

max_number_of_trees  <=  number_of_trees ; 

EFFECTS 

t = NEW ( tr ee_name) ; 

'tree(t)  * TRUE;  $(  t is  now  a valid  tree_name,  but  the 

tree  is  empty  for  now) 
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OVFUN  init ial ize_root ( t)  ->  id; 

$(  Allows  a value,  leftson,  or  rightson  to  be 
associated  with  the  root  of  tree  t.  The  value  returned 
is  the  identifier  for  the  root.  The  father  of  the  root 
is  set  to  zero.) 

EXCEPTIONS 

NOT  tree (t) ; 
size_of_tree (t)  ~=  0; 

EFFECTS 

LET  INTEGER  j | j ~=  0 AND  node(t,  j)  = ? 

$(  j was  not  in  us,e  as  a node  name) 

IN  'node  ( t , j)  =»  STRUCT  ( 0 , ?,  ?,  ?)  AND  id  = j; 

$(  j becomes  a root  since  its  father  is  0.  It  has  no 
leftson,  no  rightson,  nor  any  value  stored  at  it.) 

OVFUN  initial ize_left_son (t ; i)  ->  id; 

$(  Adds  a new  node  to  tree  t,  returning  the  identifier 
for  that  node  as  the  function's  value.  The  new  node  is  the 
leftson  of  node  i.) 

EXCEPTIONS 

NOT  tree (t) ; 

node(t,  i)  = ?; 

ex ists_lef t_son ( t , i); 

size_of  tree(t)  >=  max_number_of_nodes ; 

EFFECTS 

LET  INTEGER  j I j ~=  0 AND  node(t,  j)  = ? 

$(  j was  not  in  use  as  a node  name) 

IN  'node (t , j)  = STRUCT ( i , ?,  ?,  ?)  $(  j has  a father  i; 

its  leftson,  rightson, 
and  stored  value  are  all 
undefined) 

AND  'node(t,  i). leftson  = j $(  this  defines  that  i has  j 

as  its  leftson) 

AND  id  = j; 
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OVFUN  initialize_r ight_son(t;  i)  ->  id; 

$(  Adds  a new  node  to  tree  t,  returning  the  identifier 
for  that  node  as  the  function's  value.  The  new  node  is  the 
rightson  of  node  i.) 

EXCEPTIONS 

NOT  t r ee  ( t ) ; 

node(t,  i)  = ?; 

ex ists_r ight_son ( t , i) ; 

s i ze_of_tree ( t ) >=  max_number_of_nodes ; 

EFFECTS 

LET  INTEGER  j | j ~=  0 AND  node(t,  j)  = ? 

$(  j was  not  in  use  as  a node  name) 

IN  ' node ( t , j)  = STRUCT ( i , ?,  ?,  ?)  $(  j has  a father  i; 

its  leftson,  rightson, 
and  stored  value  are  all 
undefined) 


AND  'node(t,  i). rightson  = j 


$(  this  defines  that  i has  j 
as  its  rightson) 


AND  id  = j ; 

OFUN  set_value(t;  i;  j);  $(  This  must  be  changed  for  a data  type 

other  than  INTEGER  for  value.  Sets  the 
value  of  node  i on  tree  t to  j.) 

EXCEPTIONS 

NOT  tree  (t)  ; 
node(t,  i)  = ?; 

j < 0 - max_value  OR  j > max_value; 

EFFECTS 

'node(t,  i). value  » j; 

VFUN  preorder_traversal (t)  ->  VECTOR_OF  INTEGER  v; 

$(  Returns  a vector  of  integers,  which  represents  all 
node  identifiers  for  the  tree  t,  in  a preorder 
traversal . ) 

EXCEPTIONS 

NOT  tree (t)  ; 
size_of_tree (t)  = 0; 

DERIVATION 

preorder (t,  root_id(t)); 

VFUN  inorder_traver sal (t)  ->  VECTOR_OF  INTEGER  v; 

$(  Returns  a vector  of  integers,  which  represents  all 
node  identifiers  for  the  tree  t,  in  an  inorder 
traversal . ) 

EXCEPTIONS 

NOT  tree (t)  ; 
size_of_tree (t)  * 0; 

DERIVATION 

inorder(t,  root  id ( t ) ) ? 
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VFUN  postorder_tr aversal (t)  ->  VECTOR_OF  INTEGER  v; 

$(  Returns  a vector  of  integers,  which  represents  all 
node  identifiers  for  the  tree  t,  in  a postorder 
traversal . ) 

EXCEPTIONS 

NOT  tree (t) ; 
size_of_tree (t)  = 0; 

DERIVATION 

postorder (t,  root_id(t)); 

END  MODULE 


Appendix  V 

Character  Oriented  Editor 


A.  Key  Words:  editor,  text  editor,  character  editor,  file 


B.  References 

This  module  was  modeled  after  TECO,  an  editor  found  on  the 
DEC-10  as  well  as  other  systems.  A survey  of  on-line  editors 
along  with  examples  can  be  found  in  the  article  On-line  Text 
Editing:  A Survey,  by  Andries  Van  Dam  and  David  E.  Rice, 
Computing  Surveys,  Vol.  3,  No.  3,  September,  1971. 


C.  Hidden  Information 

The  module  hides  all  decisions  about  how  the  editor  is 
implemented.  For  instance,  users  of  the  module  cannot  assertain 
how  the  edit  file  is  stored.  Is  it  in  an  array,  a linked  list  or 
some  other  data  structure? 


D.  Description  (an  aid  to  understanding  the  definition,  though 
the  definition  is  the  arbitrator  of  all  issues  or  questions 
raised) 


This  module  represents  the  functional  capabilities  of  an 
editor.  It  is  assumed  that  an  intermediary  level  for  processing 
a command  systax  exists  between  this  and  the  user.  The  edit  file 
is  made  up  of  a sequence  of  characters.  At  no  time  .can  the  total 
number  of  characters  in  the  file  exceed  "max_f ile_size. " A line 
is  a sequence  of  characters  bracketed  by  the  implementation 
parameter  "line_end."  The  first  and  last  lines  of  a file  are 
bracketed  by  only  one  "line_end"  and  either  the  beginning  or  the 
end  of  the  file.  There  are  no  explicit  line  numbers.  Operations 
on  the  file  are  relative  to  a current  position. 

The  file  cannot  be  accessed  directly.  It  is  only  through 
the  HIDDEN  function  "file"  that  the  text  may  be  retrived.  This 
function  is  neccessary  in  order  to  describe  changes  which  effect 
the  file.  The  current  position  is  represented  by  the  HIDDEN 
function  "pointer." 

At  the  onset,  the  file  is  closed  and  uninitialized.  The 
function  "open_file"  must  be  called  before  editing  operations  may 
begin.  "Open"  is  a predicate  which  returns  true  when  the  file 
has  been  initialized.  "Close_file"  terminates  an  editing 
sess ion . 
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The  only  function  that  allows  a view  of  the  file  outside 
of  this  module  is  "display_l ines . " "Display_l ines"  makes  lines 
visible  relative  to  the  position  that  the  pointer  references  at 
the  time  of  the  function  call.  The  remaining  functions  don't 
return  a value,  they  only  have  effects  on  the  pointer  and  the 
contents  of  the  edit  file. 

The  following  functions  strictly  move  the  pointer.  They 
are,  "raove_pointer_i_characters" , "move_po inter_over_i_l ines" , 
"move_to  beginning  of_f ile" , "move_to_end_of_f ile"  and  "scan." 
"Move_poTnter_i_characters"  moves  the  pointer  foward  or  backward 
over  characters.  "Move_pointer_over_i_lines"  moves  the  pointer 
foward  or  backward  over  lines.  "Move_to_beginning_of_f ile" 
positions  the  pointer  to  the  first  character  of  the  Tile,  and 
"move_to_end_of_f ile"  positions  the  pointer  one  past  the  end  of 
the  file.  Lastly,  "scan"  is  used  to  position  the  pointer  to  the 
character  following  a given  number  of  occurrences  of  a character 
string . 


The  rest  of  the  functions  alter  the  appearance  of  the  file 
as  well  as  possibly  move  the  pointer.  They  are, 
"delete_characters" , "delete_lines" , "delete_entire_f ile" , 
" inser t_characters" , and  "replace."  "Delete_characters"  and 
"delete_l ines"  delete  characters  and  lines  from  the  file, 
respectively.  The  entire  file  can  be  deleted  via 
"delete_entire_f ile . " " Insert_characters"  is  used  to  add  text  to 
the  edit  file.  Lastly,  "replace"  substitutes  one  string  of 
characters  for  another.  „ 


E.  Modifications 

One  way  to  make  this  editor  more  robust  would  be  to  add  a 
facility  for  defining  editing  macros.  In  this  manner,  new 
editing  primitives  could  be  created  from  existing  ones. 


F.  Alternatives 

Rather  than  having  a pointer  into  the  file,  lines  of  text 
could  have  a reference  number.  Locations  for  changes  to  the  edit 
file  could  be  specified  by  using  this  line  number  as  opposed  to 
positioning  the  pointer.  See  the  specification  of 
line  oriented  editor. 
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MODULE  character_or iented_editor 

$(  It  is  probably  best  to  study  the  specification  in  the  following 
order:  the  PARAMETERS  line^end  and  max_f ile_sizey  the  VFUNs  file 
and  pointer;  the  DEFINITIONS  of  file_size,  number_of_l ines , 
end_of_line,  start_of  line,  line,  and  cur  rental ine# ; and  the 
other  FUNCTIONS,  reading  the  remaining  DEFINITIONS  as  they  are  used 
in  FUNCTIONS.) 


TYPES 

one  line:  VECTOR  OF  CHAR; 


DECLARATIONS 
INTEGER  i; 


PARAMETERS 

CHAR  line_end;  $(  character  in  the  file  indicating  the  end  of  a 

line) 

INTEGER  max_f ile_size ; $(  maximum  number  of  characters  permissible 

in  a file) 


DEFINITIONS 

$(  A line  is  a sequence  of  characters  bracketed  by 
line_ends;  the  line_end  characters  themselves  are  not 
part  of  the  line.  TEe  first  and  last  line  of  a file  are 
bracketed  by  only  one  line_end  and  either  the  beginning 
or  end  of  the  file.) 

INTEGER  f ile_size  IS  LENGTH (file ()) ; $(  The  total  number  of 

characters  in  the  file, 
including  line_ends.) 

INTEGER  number_of_l ines 

IS  1 + CARDINALITY ( { INTEGER  k I file()(k]  - line_end  }); 

$(  The  total  number  of  lines  in  the  file  is  always  one 
greater  than  the  number  of  line_ends,  since  line_ends 
act  as  separators  between  lines.) 

INTEGER  end_of_line(i) 

IS  IF  i * number_of  lines 

THEN  file_size  ?(  The  case  of  the  last  line.) 

ELSE  SOME  INTEGER  j | file ( ) [ j]  - line_end 

AND  CARDINALITY ({  INTEGER  k | 
k < j AND  file()[k]  - line_end  ))  - i - 1; 

$(  The  clause  about  the  CARDINALITY  says  that  there  are 
exactly  i-1  line_ends  prior  to  position  j.) 
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INTEGER  start_of_l ine ( i) 

IS  IF  i - 1 THEN  1 ELSE  1 + end  of  line (i  - 1); 

$(  Gives  the  position  in'the  file  of  the  first  character 
in  line  i) 

oneline  line(i) 

IS  VECTOR (FOR  j FROM  star tofl ine ( i)  TO  end  ofline(i) 

: file()ljj);  $(  The  character  string  forming  line  i) 

INTEGER  cur rent_l ine# 

IS  1 + CARDINALITY ( { INTEGER  j | file()[j]  - 1 ineend 

AND  j < po inter  ( ) } ) ; 

$(  This  is  the  line  number  of  the  line  into  which  pointer 
is  pointing.  It  is  always  true  that  the  number  of 
line_ends  intervening  between  the  beginning  of  the  file 
and  any  particular  character  position  is  one  less  than 
the  line  number  of  the  line  containing  the  particular 
character  position.  Note  that  by  this  definition,  if  the 
pointer  is  at  a line  end,  cur rent_l ine#  is  that  of  the 
line  terminated  by  tKe  line_end.) 

BOOLEAN  enough  characters  ( i ) 

IS  (i  > 0 AND  i + pointer ()  <=  file_size  + 1) 

$(  The  pointer  may  point  one  position  past  the  last 
character  in  the  file.) 

OR(i  < 0 AND  pointer  ()  + i >■  1) 

OR  i = 0 ; $(  This  is  true  if  there  are  enough  charactexs 

relative  to  the  pointer  position  to  do  the  desired 
character  operation.) 


BOOLEAN  enough_l ines ( i) 

IS  (i  > 0 AND  cur rentl ine#  + i <*  number _of_l ines  + 1) 

OR(i  < 1 AND  current_line#  + i >■  1) 

OR  i - 0;  ${  This  is  true  if  there  are  enough  lines  relative 

to  the  pointer  position  to  perform  the 
delete  lines  operation.) 


VECTOROF  CHAR  char acter_delete ( INTEGER  star tposition ; 

INTEGER  number_to_delete ; 

VECTOR  OF  CHAR  string) 

$(  This  returns  a sequence  oT  characters  identical  to 
string  except  that  a substring  has  been  deleted.  The 
substring  contains  number_to_delete  characters  and 
starts  with  star t_position. ) 

IS  VECTOR ( FOR  i FROM  1 TO  LENGTH  (str ing ) - number_to  delete 
: IF  i < start  position 
THEN  stringTi] 

ELSE  str ing (i  + number  to  delete]); 
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VECTOR_OF  CHAR  char acter_inser t ( INTEGER  insertion  point; 

VECTOROF  CHAR  inser t ion_str ing ; 

VECTOR  OF  CHAR  or  ig inalstr ing ) 

IS  $(  This  returns  a sequence  of  cKaracters  identical  to 

or  ig  inal__str  ing  except  that  string  is  added  just  before 
inser t ion _po int . ) 

VECTOR (FOR  i 

FROM  1 

TO  LENGTH ( inser tion  string)  + LENGTH (or ig inalstr ing) 

: IF  i < inser t ionpo int 
THEN  original  string(i) 

$ ( The  portion  before  the  added  characters.) 

ELSE  IF  i < insertion  point  + LENGTH (insertion  string) 
THEN  inser tion_str ing [ i - inser t ion_po int  + 1) 

$(  For  i-inser tion  point,  the  character 
in  the  resulting  string  must  be 
inser tion_str ing ( i) . ) 

ELSE  or  ig  inal  str  inq ( i - 

LENGTH  (insertion_str ing) 1 ) 
$(  The  portion  after  the  added  characters.); 

INTEGER  not_enough_matches  IS  0; 

INTEGER  no_more_matches  IS  0;  $(  Note,  it  is  the  same  value  as 

notenough  matches. ) 


BOOLEAN  atend (VECTOROF  CHAR  file  string; 

INTEGER  starting  point; 

VECTOR  OF  CHAR  string) 

IS  $(  True,  if  there  are  less  than  the  length  of  string 

characters  from  the  star ting_point.  through  to  the  end  of 
the  file_string.  True  indicates  th3t  there  can  not  be  a 
match  of  the  contents  of  strinq  in  any  substring  of 
filestring  beginning  at  start ingpoint . ) 

LENGTH (str ing ) > LENGTH ( f i lestr ing ) - star t ing_po int  + 1 

$(  The  expression  LENGTH  ( f i le_str ing ) -star t ing_po int  + 1 
is  the  number  of  characters  from  star ting_point  through 
to  the  end  of  f i le_str ing . ) ; 

BOOLEAN  a t_ma tch ( VECTOR_OF  CHAR  file  string; 

INTEGER  star ting_poTnt ; 

VECTOROF  CHAR  string) 

IS  $(  True,  if  there  is  a match  of  string  in  file_string 
beginning  at  starting_point. ) 

NOT  attend (file_str ing , starting-point,  string) 

AND  (FORALL  INTEGER  k | 


k > 0 

AND  k <-  LENGTH (str ing) ; 

string(k)  - f ile_str ing [starting_point  + k - 1)); 
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INTEGER  next_match(VECTOR_OF  CHAR  file  string? 

INTEGER  starting-point ; 

VECTOROF  CHAR  string) 

IS  $(  The  position  of  the  next  match  of  string  in  file  string 
which  occurs  on  or  after  startingpoint . If  there  Is  no 
match,  then  not  enough-matches  is  returned.) 

IF  atend (f i lestrlng , startingpoint , string) 

THEN  not_enough  matches 

ELSE  IF  at_matcK(file_string,  starting_point,  string) 

THEN  star tingpoint 

ELSE  next_match(f ilestr ing,  starting_point  + 1,  string); 

INTEGER  pos it ion_a f ter_i th_ma tch ( VECTOR— OF  CHAR  file  string; 

INTEGER  starting_poTnt; 

VECTOR_OF  CHAR  str ing_to_match ; 

INTEGER  i) 

IS  $(  The  position  just  after  the  ith  match  of  string_to  match 
in  file_string.  The  i matches  must  all  start  on  or  alter 
starting_point . ) 

IF  i - 0 

THEN  starting_point 

ELSE  IF  next_match (f ile_str ing , starting_point,  str ing_to_match) 

■ not_enough_matches 
THEN  not  enough  matches 

ELSE  posit ion_aIter_ith_match (f ile_str ing , 

nextjmatch ( f ilestr ing , 

starting_point , 
str ing_to_match) 

+ LENGTH (str ing_to  match) 

$(  The  position  Tollowing 
the  next  occurrence  of  a 
match  of  string  which 
is  on  or  after 
startingpo int) , 
str ing_to_match , i - 1) ; 

VECTOR_OF  CHAR  result_of_substitutions (VECTOR_OF  CHAR  original; 

VECTOR_OF  CHAR  old; 

VECTOR_OF  CHAR  new; 

INTEGER  star ting_point) 

IS  $(  A new  string  of  characters  where  each  occurrence  of 
the  contents  of  old  in  original  is  replaced  by  the 
contents  of  new.  Star ting_po int  references  the  next 
character  in  original  where  a match  may  begin.) 

IF  at_end (or ig inal , starting_point,  old) 

THEN  original 

ELSE  IF  at_match (or iginal , starting_point,  old) 

THEN  LET  VECTOR_OF  CHAR  updated  original  - 
character_insert (star ting_po!nt , new, 

character_delete (star ting  point, 

LENGTH (old), 
original) ) 

$(  The  result  of  one  substitution  can  be  viewed  as 
inserting  the  new  after  deleting  the  old.) 

IN  resultofsubstitut ions (updated_or ig inal , old,  new, 

starting_point  LENGTH  (new) 
$(  The  position  after  the  newly  inserted  string.)) 
ELSE  result_of_substitutions (or iginal , old,  new, 

star ting_point  ♦ 1); 
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INTEGER  poaitionaf ter  subst i tut  ions (VECTOR  OF  CHAR  original* 

VECTOR  OF  CHAR  old* 

VECTOR 'OF  CHAR  new* 

INTEGER  starting  point; 

INTEGER  number  of  matches) 

IS  $(  If  all  occurrences  of  old  in  original  star'tinq  on  or 

after  starting  point  were  replaced  by  new,  the  position 
following  the  Tast  substitution  would  equal  the  value 
returned  by  this  definition.  Number  of  matches  is  used 
to  keep  track  of  the  number  of  matches  found.) 

IF  next  match (original,  starting  point,  old)  - no  more  matches 
THEN  starting  point 

+ number  of  matches  * (LENGTH (new)  - LENGTH (old)) 

$(  Starting  point  has  either  its  original  value  when  the 
definition  was  first  used  or  points  to  the  position  after  the 
last  occurrence  of  a match  of  old  that  is  on  or  after  the 
original  star t ingpo int . To  find  the  location  of  the 
position  after  the  last  substitution  of  new  for  old, 
this  value  must  be  shifted.  The  shift  is  the  number 
of  characters  added  or  deleted  from  the  file  as  the 
result  of  a substitution  times  the  number  of 
substitutions.  LENGTH  (old)  - LENGTH  (new)  reflects 
the  number  of  characters  added  or  deleted  from 
the  file  as  a result  of  a substitution.) 

ELSE  IF  at  match (or iq inal , starting  point,  old) 

THEN  "pos i t ion  after  substitutions (original,  old,  new, 

starting  point 
♦ LENGTH (old) 

$ ( Posit  ion  where 
another  match 
may  start . ) , 
number_of  matches  ♦ l) 

ELSE  pos  i t ion  after  subst  i tut  ions  (or  ig  inal  , old',*  new, 

starting  point  + 1, 
number  oF  matches) * 


FUNCTIONS 


VFUN  file()  ->  VECTOR  OF  CHAR  vc* 
HIDDEN* 

INITIALLY 
vc  « ?* 


$(  Represents  text  to  be  edited.) 


VFUN  open()  ->  BOOLEAN  b> 


HIDDEN* 

INITIALLY 

FALSE* 


S ( Predicate,  which  returns  true  if  file 
is  open  and  therefore  ready  for 
editing . ) 


VFUN  pointer ()  ->  INTEGER  p* 


HIDDEN* 
INITIALLY 
p - 1| 


$(  Pointer  into  file  giving  the 
current  position,  from  which  most 
editing  operations  are  defined.) 
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OFUN  open_file();  $(  Defines  the  form  of  the  input  file,  upon 

which  all  editing  operations  are  performed.) 

EXCEPTIONS 
open ( ) ; 

EFFECTS 

•open()  - TRUE; 

- VECTOR (FOR  j 

FROM  1 

TO  SOME  INTEGER  k | k >*  0 AND  k <■  max  file  size 
; SOME  CHAR  c I TRUE);  “ “ 

OFUN  close  file(); 

?(  Terminates  an  editing  session.  If  further  editing  is 
to  be  done,  an  open_file  must  be  performed.  In 
integrating  this  module  into  a complete  file  package, 
the  definitions  of  open_file  and  close_file  must  be 
modified  to  reflect  (a)  that  close  file  writes  the 
modified  file  to  disk  and  (b)  the  definition,  perhaps 
via  operating  system  commands,  of  which  file  is  opened 
and  of  exceptions  corresponding  to  not  finding  a file  by 
that  name.) 

EXCEPTIONS 

NOT  open ( ) ; 

EFFECTS 

'open()  - FALSE; 

VFUN  d isplay_l ines ( i)  ->  VECTOR_OF  CHAR  vc; 

$(  This  'prints'  lines  or  makes  them  visible  relative  to 
the  current  position.  If  i>0,  then  the  current  line 
starting  at  the  current  position  will  be  displayed,  as 
well  as  i-1  lines  following  the  current  one.  If  i.<«0, 
then  the  current  line  up  to  the  position  before  current 
position  is  displayed  as  well  as  the  absolute  value  of  i 
lines  preceding  the  current  line.  Notice  that  the  value 
returned  by  d isplay_l ines  is  just  the  sequence  of 
characters  including  lineends  as  they  appear  in  the 
file;  if  the  lines  are  to  be  truly  printed,  the  line_end 
characters  must  be  used  to  generate  the  appropriate 
control  characters  for  the  particular  output  device 
involved . ) 

EXCEPTIONS 

NOT  open ( ) ; 

NOT  enough_l ines ( i) ; 

DERIVATION 
IF  i > 0 

THEN  VECTOR (FOR  j 

FROM  pointer  ( ) 

TO  end  of_l ine (cur rent_l ine#  + i - 1) 

; file()Tjl) 

ELSE  VECTOR (FOR  j 

FROM  star t_of_l ine (cur rent_l inel  + i) 

TO  pointer?)  - 1 
s file()  (jl ) 

$(  For  some  applications,  it  may  be  preferable  to  have 
d isplay_l ines  return  a sequence  of  lines  rather  than  a 
string  of  characters  with  the  line  boundaries  as 
characters.  To  do  this,  the  value  returned  should  be 
VECTOR  OF  one_line;  the  vector  is  easily  defined  using 
the  definitions  of  line  (i)  and  current  linet.); 
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OFUN  move_pointer_i_char acters ( i)  ; 

$(  If  i>0,  then  advance  the  pointer  i characters  forward. 
If  i<0,  then  move  the  pointer  back  over  the  absolute 
value  of  i characters.  If  i-0,  then  no  change  occurs.  In 
moving  the  pointer  foward,  one  is  allowed  to  move  it  one 
position  after  the  last  character  of  the  file.) 

EXCEPTIONS 

NOT  open ( ) » 

NOT  enough_character s { i ) ? 

EFFECTS 

'pointerO  * pointer()  + ij 

OFUN  move_pointer_over_i_lines ( i)  ; 

$(  This  positions  the  pointer  to  the  beginning  of  a line 
i lines  from  the  current  pointer.  That  is,  if  i-0,  the 
pointer  is  moved  to  the  beginning  of  the  current  line. 

If  i>0,  the  pointer  is  moved  to  the  beginning  of  the  ith 
line  after  the  current  one.  If  i<0,  the  pointer  is  moved 
to  the  beginning  of  the  absolute  value  of  i lines  before 
the  current  line.) 

EXCEPTIONS 

NOT  open ( ) ; 

NOT  enough_l ines ( i) ; 

EFFECTS 

'pointerO  * start  of_l  ine  (cur  rent_l  inet  + i); 

OFUN  move_to_beg inn ing_of_f i le ( ) ; $(  Moves  pointer  to  the  first 

character  of  the  file.) 

EXCEPTIONS 

NOT  open ()  ; 

EFFECTS 

'pointerO  - 1; 

OFUN  move_to_end_of_f ile () > $(  Set  the  pointer  to  the  position 

after  the  last  character  in  the  file.) 

EXCEPTIONS 

NOT  open ( ) ; 

EFFECTS 

'pointerO  - file_size  + 1; 


OFUN  delete_characters (i) ? 

$(  If  i>0,  then  the  character  indicated  by  pointer  and 
the  i-1  characters  following  it  are  deleted? 
additionally,  pointer  points  to  the  next  remaining 
character.  If  i<0,  then  the  absolute  value  of  i 
characters  preceding  the  pointer  are  deleted  and  the 
pointer  points  to  the  same  character  as  before.  If  i-0, 
this  has  no  effect.) 

EXCEPTIONS 

NOT  open ( ) » 

NOT  enough_char acters ( i) ? 

EFFECTS 

IF  i >-  0 

THEN  'fileO  - character_delete  (pointer  ()  , i,  fileO) 

ELSE  'fileO 

- character  delete  (pointer  ()  + i,  0 - i,  fileO) 

AND  ’pointer!)  * pointerO  ♦ i? 
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OFUN  delete_lines (i) ; 

$(  If  i>0,  then  all  characters  on  the  current  line  at  or 
after  pointer  are  deleted;  additionally,  the  next  i-1 
lines  are  deleted,  and  the  pointer  points  to  the  first 
character  after  the  deleted  ones.  If  i<*0,  then  all 
characters  of  the  current  line  preceding  the  pointer  are 
deleted;  additionally,  the  absolute  value  of  i lines 
preceding  current  line  are  also  deleted.  In  the  case  of 
i<»0,  the  pointer  will  continue  to  point  to  the  same 
character  as  before  the  delete.) 

EXCEPTIONS 

NOT  open ( ) ; 

NOT  enough_lines(i) ; 

EFFECTS 

IF  i > 0 

THEN  'file() 

■ character_delete (pointer () , 

end_of  line(  cur rentl ine#  * i - 1) 

- pointer!)  + 1 

$(The  number  of  characters  to 
be  deleted),  file()) 

$(  The  value  of  pointer  need  not  be  changed.  The  pointer 
afterwards  either  is  just  past  the  end  of  the  file  if 
all  lines  to  the  end  of  the  file  were  deleted,  or  is  at 
the  first  character  of  the  next  non_deleted  line.; 

ELSE  ' f ile ( ) 

* character  delete (star t_of_l ine (current_line#  + i) , 

pointer () 

- start_of_line (cur rent_l ine#  + i) 
$(  The  number  of  characters  to  be 

deleted . ) , 
file()) 

AND  'pointer  ()  * star '._of_l  ine  (cur  rent_l  inel  + i)  ; 

OFUN  delete_entire_f ile { ) ; $(  This  deletes  the  edited  copy  of  the 

file.) 

EXCEPTIONS 

NOT  open ( ) ; 

EFFECTS 

'f  ile()  * VECTOR  ()  ; 

'pointerO  * 1; 

OFUN  inser t_character s (VECTOR_OF  CHAR  string); 

$T  This  operation  adds  the  string  just  before  the 
pointer.  However,  the  pointer  continues  to  point  to  the 
same  character.  String  may  in  fact  include  line_ends; 
therefore  adding  several  lines  to  a file.  If  one  wants 
to  add  new  lines  to  the  end  of  the  file,  one  should  move 
the  pointer  to  the  position  after  the  last  character  in 
the  file;  in  this  case,  string  should  begin  with  a 
line_end  if  the  last  character  in  the  file  is  not  a 
line_end . ) 

EXCEPTIONS 

NOT  open () ; 

file  size  + LENGTH (str ing)  > max_f ile_si*e; 

EFFECTS" 

*file()  ■ character_insert (pointer () , string,  file()); 
•pointerO  * pointerO  + LENGTH  (str  ing) ; 
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OF UN  scan (VECTOR  OF  CHAR  string;  INTEGER  i); 

$(  This  operation  moves  the  pointer  to  just  after  the  ith 
occurrence  of  string  occurring  at  or  after  the  pointer 
in  the  file.) 

EXCEPTIONS 

NOT  open ( ) ; 

. LENGTH (string)  * 0; 

i <■  0 ; 

position_after_ith_match (f ile () , pointer (),  string,  i) 

• ■ not_enough_matches ; 

EFFECTS 

’pointer ( ) 

» position_af ter_ith_match ( f ile ( ) , pointerO,  string,  i); 

OFUN  replace (VECTOROF  CHAR  old;  VECTOR_OF  CHAR  new); 

$ ( This  substitutes  the  new  string  for  the  old  string 
whenever  old  occurs  starting  at  or  after  the  pointer. 
Additionally,  the  pointer  is  positioned  to  the  character 
following  the  last  substitution.) 

EXCEPTIONS 

NOT  open ( ) ; 

LENGTH (old)  - 0; 
max_f ile_size 

< LENGTH  (result_of_subst  itutions  ( f ile  ()  , old,  new,  pointerO)); 
EFFECTS 

•file() 

* result_of_substitutions  (f  ile  ( ) , old,  new,  pointerO); 

’pointer  ( ) 

= posit  ion_after_subst  itutions  ( f ile  ()  , old,  new,  pointerO, 

0)  ; 

END  MODULE 


s 


